POST
/
customers
curl --request POST \
  --url https://api.withorb.com/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "name": "<string>",
  "email": "jsmith@example.com",
  "timezone": "<string>",
  "external_customer_id": "<string>",
  "payment_provider_id": "<string>",
  "payment_provider": "quickbooks",
  "shipping_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "currency": "<string>",
  "tax_id": {
    "country": "AD",
    "type": "ad_nrt",
    "value": "<string>"
  },
  "auto_collection": true,
  "email_delivery": true,
  "tax_configuration": {
    "tax_exempt": true,
    "tax_provider": "avalara",
    "tax_exemption_code": "<string>"
  },
  "reporting_configuration": {
    "exempt": true
  },
  "accounting_sync_configuration": {
    "excluded": true,
    "accounting_providers": [
      {
        "provider_type": "<string>",
        "external_provider_id": "<string>"
      }
    ]
  },
  "additional_emails": [
    "jsmith@example.com"
  ],
  "hierarchy": {
    "parent_customer_id": "<string>",
    "child_customer_ids": [
      "<string>"
    ]
  }
}'
{
  "metadata": {},
  "id": "<string>",
  "external_customer_id": "<string>",
  "name": "<string>",
  "email": "<string>",
  "timezone": "<string>",
  "payment_provider_id": "<string>",
  "payment_provider": "quickbooks",
  "created_at": "2023-11-07T05:31:56Z",
  "shipping_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "balance": "<string>",
  "currency": "<string>",
  "tax_id": {
    "country": "AD",
    "type": "ad_nrt",
    "value": "<string>"
  },
  "auto_collection": true,
  "exempt_from_automated_tax": true,
  "email_delivery": true,
  "additional_emails": [
    "<string>"
  ],
  "portal_url": "<string>",
  "accounting_sync_configuration": {
    "excluded": true,
    "accounting_providers": [
      {
        "provider_type": "quickbooks",
        "external_provider_id": "<string>"
      }
    ]
  },
  "reporting_configuration": {
    "exempt": true
  },
  "hierarchy": {
    "parent": {
      "id": "<string>",
      "external_customer_id": "<string>"
    },
    "children": [
      {
        "id": "<string>",
        "external_customer_id": "<string>"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Body

application/json

Response

201
application/json
Created

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.