> For the complete documentation index, see [llms.txt](https://docs.marsproxies.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marsproxies.com/marsproxies-documentation/overview/residential-proxies/api/orders.md).

# Orders

Residential order management — list, show, create, calculate pricing

## Calculate pricing for a residential order

> Returns the total price for a residential order of the given quantity, optionally applying a coupon. Does not create the order.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"CalculateResidentialOrderPricingResponse":{"title":"Calculate Residential Order Pricing Response","description":"Total price for the requested residential traffic quantity, optionally discounted by coupon.","required":["total"],"properties":{"total":{"description":"Calculated total price in USD.","type":"string"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}},"CalculateResidentialOrderPricingActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"quantity":{"type":"array","items":{"type":"string","enum":["The quantity field is required.","The quantity must be an integer.","The quantity must be at least 1."]}},"coupon_code":{"type":"array","items":{"type":"string","enum":["The coupon code must be a string."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders/calculate-pricing":{"get":{"tags":["residential-orders"],"summary":"Calculate pricing for a residential order","description":"Returns the total price for a residential order of the given quantity, optionally applying a coupon. Does not create the order.","operationId":"calculateResidentialOrderPricing","parameters":[{"name":"quantity","in":"query","description":"Amount of residential traffic to price, in gigabytes.","required":true,"schema":{"type":"integer"}},{"name":"coupon_code","in":"query","description":"Optional coupon code to apply to the calculation.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Calculated pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResidentialOrderPricingResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"422":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResidentialOrderPricingActionValidationError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## List residential orders

> Returns a paginated list of residential orders for the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"ResidentialOrderCollection":{"title":"Residential Order Collection","description":"Paginated list of residential orders.","required":["data","meta"],"properties":{"data":{"description":"Orders on the current page.","type":"array","items":{"$ref":"#/components/schemas/ResidentialOrderResource"}},"meta":{"description":"Pagination metadata.","required":["current_page","last_page","per_page","total"],"properties":{"current_page":{"description":"Current page number.","type":"integer"},"last_page":{"description":"Last available page number.","type":"integer"},"per_page":{"description":"Number of items per page.","type":"integer"},"total":{"description":"Total number of orders across all pages.","type":"integer"}},"type":"object"}},"type":"object"},"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}},"GetResidentialOrdersActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"page":{"type":"array","items":{"type":"string","enum":["The page must be an integer.","The page must be at least 1.","The page must not be greater than 10000."]}},"per_page":{"type":"array","items":{"type":"string","enum":["The per page must be an integer.","The per page must be at least 1.","The per page must not be greater than 100."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders":{"get":{"tags":["residential-orders"],"summary":"List residential orders","description":"Returns a paginated list of residential orders for the account.","operationId":"getResidentialOrders","parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Number of orders per page (1-100). Defaults to 20.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated residential orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderCollection"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"422":{"description":"Pagination parameters failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResidentialOrdersActionValidationError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## Create a residential order

> Purchases a residential order for the account. Payment is made either from the account balance or from a saved card when \`card\_id\` is supplied.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"CreateResidentialOrderRequest":{"title":"Create Residential Order Request","description":"Payload for purchasing a residential order.","required":["quantity"],"properties":{"quantity":{"description":"Amount of residential traffic to purchase, in gigabytes.","type":"integer"},"coupon_code":{"description":"Optional coupon code to apply to the order for a discount.","type":["string","null"]},"card_id":{"description":"Optional saved card identifier to charge. Omit to charge the account balance.","type":["integer","null"]}},"type":"object"},"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}},"CreateResidentialOrderActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"quantity":{"type":"array","items":{"type":"string","enum":["The quantity field is required.","The quantity must be an integer.","The quantity must be at least 1."]}},"coupon_code":{"type":"array","items":{"type":"string","enum":["The coupon code must be a string."]}},"card_id":{"type":"array","items":{"type":"string","enum":["The card id must be an integer."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders":{"post":{"tags":["residential-orders"],"summary":"Create a residential order","description":"Purchases a residential order for the account. Payment is made either from the account balance or from a saved card when `card_id` is supplied.","operationId":"createResidentialOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResidentialOrderRequest"}}}},"responses":{"200":{"description":"Created residential order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResource"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"402":{"description":"Account balance is not sufficient to complete the order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResidentialOrderActionValidationError"}}}},"423":{"description":"Another order for this account is currently being processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## Get a residential order

> Returns a single residential order owned by the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}}}},"paths":{"/v1/residential/orders/{order}":{"get":{"tags":["residential-orders"],"summary":"Get a residential order","description":"Returns a single residential order owned by the account.","operationId":"getResidentialOrder","parameters":[{"name":"order","in":"path","description":"Residential order identifier.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Residential order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResource"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Order not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```