Customers | Paid | Documentation

The Customer Object

1 class Customer
2   attr_accessor :id, :organization_id, :name, :phone, :employee_count,
3                 :annual_revenue, :tax_exempt_status, :creation_source,
4                 :website, :external_id, :billing_address
5 end
6 
7 class Address
8   attr_accessor :line1, :line2, :city, :state, :zip_code, :country
9 end
10 
11 module TaxExemptStatus
12   NONE = "none"
13   EXEMPT = "exempt" 
14   REVERSE = "reverse"
15 end
16 
17 module CreationSource
18   MANUAL = "manual"
19   API = "api"
20   CRM = "crm"
21   OTHER = "other"
22 end

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the customer
`organization_id`	string	Organization ID the customer belongs to
`name`	string	Name of the customer
`phone`	string	Optional phone number
`employee_count`	number	Optional number of employees
`annual_revenue`	number	Optional annual revenue
`tax_exempt_status`	string	Optional tax exempt status (‘none’, ‘exempt’, ‘reverse’)
`creation_source`	string	Optional source of creation (‘manual’, ‘api’, ‘crm’, ‘other’)
`website`	string	Optional website URL
`external_id`	string	Optional external identifier
`billing_address`	object	Optional billing address information

Address Attributes

Attribute	Type	Description
`line1`	string	First line of the address
`line2`	string	Optional second line of the address
`city`	string	City name
`state`	string	State or province
`zip_code`	string	ZIP or postal code
`country`	string	Country name

API Endpoints

Create a Customer

Creates a new customer with the given data.

SDK Functions

Ruby

1 require 'paid_ruby'
2 
3 # Initialize the client
4 api = Paid::Client.new(
5     token: "YOUR-API-KEY"
6 )
7 
8 # Create ther customer
9 customer = api.customers.create(
10     name: "Acme Corporation",
11     phone: "+1-555-0123",
12     employee_count: 100,
13     annual_revenue: 1000000,
14     tax_exempt_status: Paid::TaxExemptStatus::NONE,
15     creation_source: Paid::CreationSource::API,
16     website: "https://acme.com",
17     external_id: "acme_123",
18     billing_address: {
19         line1: "123 Business Ave",
20         line2: "Suite 100",
21         city: "San Francisco",
22         state: "CA",
23         zip_code: "94105",
24         country: "USA"
25     }
26 )

Returns

Returns the Customer object upon successful creation. It’s recommended to store the returned customer ID in your own system for future reference and operations.

1 {
2   id: "uuid",
3   organization_id: "uuid", 
4   name: "Acme Corporation",
5   phone: "+1-555-0123",
6   website: "https://acme.com",
7   employee_count: 100,
8   annual_revenue: 1000000,
9   tax_exempt_status: "none",
10   creation_source: "api",
11   external_id: "acme_123",
12   creation_state: "active",
13   billing_address: {
14     city: "San Francisco",
15     line1: "123 Business Ave", 
16     line2: "Suite 100",
17     state: "CA",
18     country: "USA",
19     zip_code: "94105"
20   }
21 }

Retrieve a Customer

Retrieves a customer by its internal and/or external IDs.

SDK Functions

Ruby

1 # Retrieve customer using its internal ID
2 customer = api.customers.get(customer_id: id)
3 
4 # Retrieve customer using its external (custom) ID
5 customer = api.customers.get_by_external_id(external_id: external_id)

Returns

Returns the up-to-date Customer object for a valid identifier. Raises an error if parameters are invalid (e.g. specifying an invalid internal/external customer IDs.

1 {
2   id: "uuid",
3   organization_id: "uuid", 
4   name: "Acme Corporation",
5   phone: "+1-555-0123",
6   website: "https://acme.com",
7   employee_count: 100,
8   annual_revenue: 1000000,
9   tax_exempt_status: "none",
10   creation_source: "api",
11   external_id: "acme_123",
12   creation_state: "active",
13   billing_address: {
14     city: "San Francisco",
15     line1: "123 Business Ave", 
16     line2: "Suite 100",
17     state: "CA",
18     country: "USA",
19     zip_code: "94105"
20   }
21 }

List all Customers

Retrieves all customers associated with your organization.

Ruby

1 # List all customers
2 customers = api.customers.list()

Returns

Returns the up-to-date list of Customer objects.

1 [
2 	{
3   		id: 'uuid',
4   		organization_id: 'uuid',
5   		name: 'Acme Corporation',
6   		phone: '+1-555-0123',
7   		...
8 	},
9 	{
10   		id: 'uuid',
11   		organization_id: 'uuid',
12   		name: 'Emca Corporation ',
13   		phone: '+1-555-0123',
14   		...
15 	}
16 ]

Update a Customer

Updates an existing customer by its internal and/or external IDs.

SDK Functions

Ruby

1 # Update customer using its internal ID
2 update_data = {
3     name: "Acme Corp",
4     phone: "+1-555-0124",
5     employee_count: 150
6 }
7 
8 customer = api.customers.update(
9     customer_id: id,
10     request: update_data
11 )
12 
13 # Update customer using its external (custom) ID
14 customer = api.customers.update_by_external_id(
15     external_id: id,
16     request: update_data
17 )

Returns

Returns the updated Customer if the update succeeded. Raises an error if update parameters are invalid (e.g. specifying an invalid customer ID)

1 {
2   id: "uuid",
3   organization_id: "uuid", 
4   name: "Acme Corporation",
5   phone: "+1-555-0123",
6   website: "https://acme.com",
7   employee_count: 100,
8   annual_revenue: 1000000,
9   tax_exempt_status: "none",
10   creation_source: "api",
11   external_id: "acme_123",
12   creation_state: "active",
13   billing_address: {
14     city: "San Francisco",
15     line1: "123 Business Ave", 
16     line2: "Suite 100",
17     state: "CA",
18     country: "USA",
19     zip_code: "94105"
20   }
21 }

Delete a Customer

Deletes a customer by its internal and/or external IDs.

SDK Functions

Ruby

1 # Delete customer using its internal ID
2 api.customers.delete(customer_id: id)
3 
4 # Delete customer using its external (custom) ID
5 api.customers.delete_by_external_id(external_id: id)

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests:

2xx range indicates success
4xx range indicates an error that failed given the information provided
5xx range indicates an error with Paid’s servers

Error Response Format

1 {
2   "error": {
3     "message": "Error message",
4     "code": "ERROR_CODE",
5     "details": "Additional error details"
6   }
7 }

Common Error Codes

Code	Description
`ACCOUNT_NOT_FOUND`	The specified customer does not exist
`INVALID_REQUEST`	The request was invalid
`UNAUTHORIZED`	The API key is invalid
`FORBIDDEN`	The API key doesn’t have permission to access the resource
`INTERNAL_SERVER_ERROR`	An error occurred on Paid’s servers