Orders | Paid | Documentation

The Order Object

1 class Order
2   attr_accessor :id,                   
3                 :name,                 
4                 :description,          
5                 :account_id,           
6                 :organization_id,      
7                 :start_date,          
8                 :end_date,            
9                 :total_amount,        
10                 :estimated_tax,       
11                 :billed_amount_no_tax, 
12                 :billed_tax,          
13                 :total_billed_amount, 
14                 :pending_billing_amount, 
15                 :order_lines,         
16                 :account,             
17                 :creation_state       
18 end
19 
20 class OrderLine
21   attr_accessor :id,                  
22                 :order_id,            
23                 :agent_id,            
24                 :name,                
25                 :description,         
26                 :start_date,          
27                 :end_date,            
28                 :total_amount,        
29                 :billed_amount_without_tax, 
30                 :billed_tax,          
31                 :total_billed_amount, 
32                 :agent,               
33                 :order_line_attributes, 
34                 :creation_state 
35 end
36 
37 class OrderLineAttribute
38   attr_accessor :agent_attribute_id, 
39                 :quantity,           
40                 :currency,           
41                 :pricing             
42 end
43 
44 class OrderLineAttributePricing
45   attr_accessor :event_name,         
46                 :charge_type,        
47                 :price_point,        
48                 :pricing_model,      
49                 :billing_frequency   
50 end
51 
52 class PricePoint
53   attr_accessor :currency,           
54                 :unit_price,         
55                 :tiers,              
56                 :min_quantity,       
57                 :included_quantity   
58 end
59 
60 class Tier
61   attr_accessor :lower_bound,        
62                 :upper_bound,        
63                 :price               
64 end
65 
66 module ChargeType
67   ONE_TIME = "oneTime"
68   RECURRING = "recurring"
69   USAGE = "usage"
70   SEAT_BASED = "seatBased"
71 end
72 
73 module PricingModelType
74   PER_UNIT = "PerUnit"
75   VOLUME_PRICING = "VolumePricing"
76   GRADUATED_PRICING = "GraduatedPricing"
77 end
78 
79 module BillingFrequency
80   MONTHLY = "Monthly"
81   QUARTERLY = "Quarterly"
82   SEMI_ANNUAL = "SemiAnnual"
83   ANNUAL = "Annual"
84 end
85 
86 module CreationState
87   DRAFT = "draft"
88   ACTIVE = "active"
89 end
90 
91 module Currency
92   USD = "USD"
93   EUR = "EUR"
94   GBP = "GBP"
95 end

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the order
`name`	string	Name of the order
`description`	string	Optional description of the order
`account_id`	string	ID of the account this order belongs to
`organization_id`	string	Organization ID the order belongs to
`start_date`	string	Start date of the order
`end_date`	string	Optional end date of the order
`total_amount`	number	Total amount of the order
`estimated_tax`	number	Estimated tax amount
`billed_amount_no_tax`	number	Billed amount without tax
`billed_tax`	number	Billed tax amount
`total_billed_amount`	number	Total billed amount including tax
`pending_billing_amount`	number	Amount pending billing
`order_lines`	array	List of order lines
`account`	object	Optional account information
`creation_state`	string	Order creation state (‘draft’ or ‘active’)

Order Line Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the order line
`order_id`	string	ID of the order this line belongs to
`agent_id`	string	ID of the agent
`name`	string	Name of the order line
`description`	string	Description of the order line
`start_date`	string	Start date of the order line
`end_date`	string	Optional end date of the order line
`total_amount`	number	Total amount of the order line
`billed_amount_without_tax`	number	Billed amount without tax
`billed_tax`	number	Billed tax amount
`total_billed_amount`	number	Total billed amount including tax
`agent`	object	Optional agent information
`order_line_attributes`	array	List of order line attributes
`creation_state`	string	Order line creation state (‘draft’ or ‘active’)

Order Line Attribute

Attribute	Type	Description
`agent_attribute_id`	string	ID of the agent attribute
`quantity`	number	Quantity of the attribute
`currency`	string	Currency code
`pricing`	object	Pricing configuration

Order Line Attribute Pricing

Attribute	Type	Description
`event_name`	string	Name of the event
`charge_type`	string	Type of charge (‘oneTime’, ‘recurring’, ‘usage’, ‘seatBased’)
`price_point`	object	Price point configuration
`pricing_model`	string	Type of pricing model (‘PerUnit’, ‘VolumePricing’, ‘GraduatedPricing’)
`billing_frequency`	string	Billing frequency (‘Monthly’, ‘Quarterly’, ‘SemiAnnual’, ‘Annual’)

Price Point

Attribute	Type	Description
`currency`	string	Currency code
`unit_price`	number	Base unit price
`tiers`	array	List of pricing tiers
`min_quantity`	number	Minimum quantity
`included_quantity`	number	Included quantity

Tier

Attribute	Type	Description
`lower_bound`	number	Lower bound of the tier
`upper_bound`	number	Optional upper bound of the tier
`price`	number	Price for this tier

API Endpoints

Create an Order

Creates a new order with 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 order = api.orders.create(
9     name: "AI SDR – Pro plan",
10     customer_id: customer_id, # use either customer_id or customer_external_id for order creation
11     billing_contact_id: billing_contact_id,
12     description: "Annual subscription for AI SDR – Pro plan",
13     start_date: "2025-06-01",
14     end_date: "2026-05-31",
15     currency: "USD",
16     order_lines: [
17         {
18             agent_external_id: "ai_agent_123", # use either agent_id or agent_external_id for order creation
19             name: "AI SDR",
20             description: "AI SDR – agent"
21         }
22     ]
23 )

Returns

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

1 {
2   "id": "uuid",
3   "organization_id": "uuid", 
4   "name": "Enterprise AI Assistant Package",
5   "start_date": "2024-01-01T00:00:00.000Z",
6   "end_date": "2024-12-31T00:00:00.000Z",
7   "order_amount": 0,
8   "estimated_tax": 0,
9   "billed_amount_no_tax": 0,
10   "billed_tax": 0,
11   "pending_billing_amount": 0,
12   "total_billed_amount": 0,
13   "total_amount": 0,
14   "creation_state": "draft",
15   "usage_summary": [],
16   "account": {
17     "id": "uuid",
18     "organization_id": "uuid",
19     "name": "Acme Test Corporation", 
20     "email": "contact@acme.com",
21     "phone": "",
22     "website": "https://acme.com",
23     "employee_count": 100,
24     "annual_revenue": 1000000,
25     "tax_exempt_status": "exempt",
26     "creation_source": "api",
27     "external_id": "customer-123",
28     "creation_state": "active",
29     "billing_address": {
30       "city": "New York",
31       "line1": "123 Main St",
32       "line2": "Suite 100", 
33       "state": "NY",
34       "country": "USA",
35       "zip_code": "10001"
36     }
37   },
38   "account_id": "uuid",
39   "order_lines": [...]
40 }

Retrieve an Order

Retrieves an order by its internal ID.

SDK Functions

Ruby

1 # Retrieve order by its internal ID
2 order = api.orders.get(order_id: id)

1 {
2   "id": "uuid",
3   "organization_id": "uuid", 
4   "name": "Enterprise AI Assistant Package",
5   "start_date": "2024-01-01T00:00:00.000Z",
6   "end_date": "2024-12-31T00:00:00.000Z",
7   "order_amount": 0,
8   "estimated_tax": 0,
9   "billed_amount_no_tax": 0,
10   "billed_tax": 0,
11   "pending_billing_amount": 0,
12   "total_billed_amount": 0,
13   "total_amount": 0,
14   "creation_state": "draft",
15   "usage_summary": [],
16   "account": {
17     "id": "uuid",
18     "organization_id": "uuid",
19     "name": "Acme Test Corporation",
20     "email": "contact@acme.com", 
21     "phone": "",
22     "website": "https://acme.com",
23     "employee_count": 100,
24     "annual_revenue": 1000000,
25     "tax_exempt_status": "exempt",
26     "creation_source": "api",
27     "external_id": "customer-123",
28     "creation_state": "active",
29     "billing_address": {
30       "city": "New York",
31       "line1": "123 Main St",
32       "line2": "Suite 100",
33       "state": "NY", 
34       "country": "USA",
35       "zip_code": "10001"
36     }
37   },
38   "account_id": "uuid",
39   "order_lines": [...]
40 }

Returns

Returns the up-to-date Order object for a valid identifier. Raises an error if get parameters are invalid (e.g. specifying an invalid internal order ID)

List all Orders

Retrieves all orders associated with your organization.

Ruby

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

Returns

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

1 [
2 	{
3 	    id: 'uuid',
4       organization_id: 'uuid',
5   		name: 'Order 1',
6   		start_date: '2024-01-01T00:00:00.000Z',
7   		end_date: '2024-12-31T00:00:00.000Z',
8   		...
9 	},
10 	{
11 	    id: 'uuid',
12       organization_id: 'uuid',
13   		name: 'Order 2',
14   		start_date: '2024-01-01T00:00:00.000Z',
15   		end_date: '2024-12-31T00:00:00.000Z',
16   		...
17 	}
18 ]

Update Order Lines

Adds/removes order lines for an exisiting order using order’s and agent’s internal IDs. Raises an error if parameters are invalid (e.g. specifying an invalid internal order ID)

SDK Functions

Ruby

1 order = api.orders.lines.update(order_id: id, lines:[
2     {
3         agent_external_id: "sdk-agent-3",
4         name: "Analytics Dashboard Add-on",
5         description: "Real-time analytics and reporting dashboard for AI assistant performance"
6     }
7 ])

1   "order_lines": [
2     {
3       "id": "uuid",
4       "order_id": "uuid",
5       "name": "Customer Support AI", 
6       "description": "AI-powered customer support agent",
7       "total_amount": 0,
8       "billed_amount_without_tax": 0,
9       "billed_tax": 0,
10       "total_billed_amount": 0,
11       "start_date": "2025-05-12T14:46:09.465Z",
12       "end_date": null,
13       "creation_state": "active",
14       "agent_id": "uuid",
15       "agent": {
16         "id": "uuid",
17         "organization_id": "uuid",
18         "name": "Zhalyn Kabyken Updated",
19         "description": "Updated description with more features",
20         "active": true,
21         "external_id": "UPDATED_AI_AGENT_001",
22         "agent_code": "UPDATED_AI_AGENT_TEST"
23       },
24       "order_line_attributes": [
25         {
26           "id": "uuid",
27           "order_line_id": "uuid",
28           "quantity": 0,
29           "currency": "USD",
30           "status": "",
31           "total_amount": 0,
32           "last_billing_date": null,
33           "next_billing_date": null,
34           "billing_cycle_start": null,
35           "billing_cycle_end": null,
36           "creation_state": "active",
37           "agent_attribute_id": "uuid",
38           "agent_attributes": {
39             "id": "uuid",
40             "name": "subscription",
41             "active": true,
42             "agent_id": "uuid"
43           },
44           "pricing": {
45             "taxable": true,
46             "event_name": "subscription",
47             "charge_type": "recurring",
48             "price_points": {
49               "USD": {
50                 "tiers": [
51                   {
52                     "unit_price": 99.99,
53                     "max_quantity": 100,
54                     "min_quantity": 0
55                   }
56                 ],
57                 "unit_price": 99.99,
58                 "min_quantity": 0,
59                 "included_quantity": 0
60               }
61             },
62             "pricing_model": "GraduatedPricing",
63             "billing_frequency": "Annual"
64           }
65         },
66         {
67           "id": "uuid",
68           "order_line_id": "uuid",
69           "quantity": 0,
70           "currency": "USD",
71           "status": "",
72           "total_amount": 0,
73           "last_billing_date": null,
74           "next_billing_date": null,
75           "billing_cycle_start": null,
76           "billing_cycle_end": null,
77           "creation_state": "active",
78           "agent_attribute_id": "uuid",
79           "agent_attributes": {
80             "id": "uuid",
81             "name": "subscription 2",
82             "active": true,
83             "agent_id": "uuid"
84           },
85           "pricing": {
86             "taxable": true,
87             "event_name": "subscription 2",
88             "charge_type": "usage",
89             "pricing_model": "VolumePricing",
90             "billing_frequency": "Monthly",
91             "price_points": {
92               "USD": {
93                 "unit_price": 99.99,
94                 "tiers": [
95                   {
96                     "unit_price": 99.99,
97                     "max_quantity": 100,
98                     "min_quantity": 0
99                   }
100                 ],
101                 "min_quantity": 0,
102                 "included_quantity": 0
103               }
104             }
105           }
106         },
107 		{
108 		// additional attributes
109 		}
110       ]
111     }
112   ]

Returns

Returns a list of OrderLine objects upon successful addition of order lines.

Activate an Order

Activates a draft order by its internal ID.

SDK Functions

Ruby

1 # Activate order by its internal ID
2   order = api.orders.activate(order_id: id)

Returns

Returns the up-to-date Order object. If the order ID does not exist, this call raises an error.

Delete an Order

Deletes an order by its internal ID.

SDK Functions

Ruby

1 # Delete order by its internal ID
2 api.orders.delete(order_id: id)

Returns

This is a void function. It performs the requested operation but does not return any value upon success. If the order ID does not exist, this call raises an error.

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
`ORDER_NOT_FOUND`	The specified order 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