> ## Documentation Index > Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Customer > Create a customer. **Scopes**: `customers:write` ## OpenAPI ````yaml post /v1/customers/ openapi: 3.1.0 info: title: Macropay API summary: Macropay HTTP and Webhooks API description: Read the docs at https://macropay.ai/docs/api-reference version: 0.1.0 servers: - url: https://api.macropay.ai description: Production environment x-speakeasy-server-id: production - url: https://sandbox-api.macropay.ai description: Sandbox environment x-speakeasy-server-id: sandbox security: - access_token: [] tags: - name: public description: >- Endpoints shown and documented in the Macropay API documentation and available in our SDKs. - name: private description: >- Endpoints that should appear in the schema only in development to generate our internal JS SDK. - name: mcp description: Endpoints enabled in the MCP server. paths: /v1/customers/: post: tags: - customers - public - mcp summary: Create Customer description: |- Create a customer. **Scopes**: `customers:write` operationId: customers:create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerCreate' responses: '201': description: Customer created. content: application/json: schema: $ref: '#/components/schemas/CustomerWithMembers' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: go label: Go (SDK) source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tmacropaygo \"github.com/web3group/macropay-go-main\"\n\t\"github.com/web3group/macropay-go-main/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := macropaygo.New(\n macropaygo.WithSecurity(os.Getenv(\"MACROPAY_ACCESS_TOKEN\")),\n )\n\n res, err := s.Customers.Create(ctx, components.CustomerCreate{\n ExternalID: macropaygo.Pointer(\"usr_1337\"),\n Email: \"customer@example.com\",\n Name: macropaygo.Pointer(\"John Doe\"),\n BillingAddress: &components.AddressInput{\n Country: components.CountryAlpha2InputUs,\n },\n TaxID: []*components.CustomerCreateTaxID{\n macropaygo.Pointer(components.CreateCustomerCreateTaxIDStr(\n \"911144442\",\n )),\n macropaygo.Pointer(components.CreateCustomerCreateTaxIDStr(\n \"us_ein\",\n )),\n },\n OrganizationID: macropaygo.Pointer(\"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"),\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.Customer != nil {\n // handle response\n }\n}" - lang: python label: Python (SDK) source: |- import macropay_sdk from macropay_sdk import Macropay with Macropay( access_token="", ) as macropay: res = macropay.customers.create(request={ "external_id": "usr_1337", "email": "customer@example.com", "name": "John Doe", "billing_address": { "country": macropay_sdk.CountryAlpha2Input.US, }, "tax_id": [ "911144442", "us_ein", ], "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737", "owner": { "email": "member@example.com", "name": "Jane Doe", "external_id": "usr_1337", }, }) # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { Macropay } from "@macropayments/sdk"; const macropay = new Macropay({ accessToken: process.env["MACROPAY_ACCESS_TOKEN"] ?? "", }); async function run() { const result = await macropay.customers.create({ externalId: "usr_1337", email: "customer@example.com", name: "John Doe", billingAddress: { country: "US", }, taxId: [ "911144442", "us_ein", ], type: "individual", organizationId: "1dbfc517-0bbf-4301-9ba8-555ca42b9737", owner: { email: "member@example.com", name: "Jane Doe", externalId: "usr_1337", }, }); console.log(result); } run(); - lang: php label: PHP (SDK) source: |- declare(strict_types=1); require 'vendor/autoload.php'; use Macropay; use Macropay\Models\Components; $sdk = Macropay\Macropay::builder() ->setSecurity( '' ) ->build(); $request = new Components\CustomerCreate( externalId: 'usr_1337', email: 'customer@example.com', name: 'John Doe', billingAddress: new Components\AddressInput( country: Components\CountryAlpha2Input::Us, ), taxId: [ '911144442', 'us_ein', ], organizationId: '1dbfc517-0bbf-4301-9ba8-555ca42b9737', owner: new Components\OwnerCreate( email: 'member@example.com', name: 'Jane Doe', externalId: 'usr_1337', ), ); $response = $sdk->customers->create( request: $request ); if ($response->customerWithMembers !== null) { // handle response } components: schemas: CustomerCreate: properties: metadata: additionalProperties: anyOf: - type: string maxLength: 500 minLength: 1 - type: integer - type: number - type: boolean propertyNames: maxLength: 40 minLength: 1 type: object maxProperties: 50 title: Metadata description: |- Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**. external_id: anyOf: - type: string - type: 'null' title: External Id description: >- The ID of the customer in your system. This must be unique within the organization. Once set, it can't be updated. examples: - usr_1337 email: type: string format: email title: Email description: >- The email address of the customer. This must be unique within the organization. examples: - customer@example.com name: anyOf: - type: string maxLength: 256 description: The name of the customer. examples: - John Doe - type: 'null' title: Name billing_address: anyOf: - $ref: '#/components/schemas/AddressInput' - type: 'null' tax_id: anyOf: - prefixItems: - type: string - $ref: '#/components/schemas/TaxIDFormat' type: array maxItems: 2 minItems: 2 examples: - - '911144442' - us_ein - - FR61954506077 - eu_vat - type: 'null' title: Tax Id type: anyOf: - $ref: '#/components/schemas/CustomerType' - type: 'null' description: >- The type of customer. Defaults to 'individual'. Set to 'team' for customers that can have multiple members. examples: - individual organization_id: anyOf: - type: string format: uuid4 description: The organization ID. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 x-macropay-selector-widget: displayProperty: name resourceName: Organization resourceRoot: /v1/organizations - type: 'null' title: Organization Id description: >- The ID of the organization owning the customer. **Required unless you use an organization token.** owner: anyOf: - $ref: '#/components/schemas/OwnerCreate' - type: 'null' description: >- Optional owner member to create with the customer. If not provided, an owner member will be automatically created using the customer's email and name. type: object required: - email title: CustomerCreate CustomerWithMembers: properties: id: type: string format: uuid4 title: Id description: The ID of the customer. examples: - 992fae2a-2a17-4b7a-8d9e-e287cf90131b created_at: type: string format: date-time title: Created At description: Creation timestamp of the object. modified_at: anyOf: - type: string format: date-time - type: 'null' title: Modified At description: Last modification timestamp of the object. metadata: $ref: '#/components/schemas/MetadataOutputType' external_id: anyOf: - type: string - type: 'null' title: External Id description: >- The ID of the customer in your system. This must be unique within the organization. Once set, it can't be updated. examples: - usr_1337 email: type: string title: Email description: >- The email address of the customer. This must be unique within the organization. examples: - customer@example.com email_verified: type: boolean title: Email Verified description: >- Whether the customer email address is verified. The address is automatically verified when the customer accesses the customer portal using their email address. examples: - true type: anyOf: - $ref: '#/components/schemas/CustomerType' - type: 'null' description: >- The type of customer: 'individual' for single users, 'team' for customers with multiple members. Legacy customers may have NULL type which is treated as 'individual'. examples: - individual name: anyOf: - type: string - type: 'null' title: Name description: The name of the customer. examples: - John Doe billing_address: anyOf: - $ref: '#/components/schemas/Address' - type: 'null' tax_id: anyOf: - prefixItems: - type: string - $ref: '#/components/schemas/TaxIDFormat' type: array maxItems: 2 minItems: 2 examples: - - '911144442' - us_ein - - FR61954506077 - eu_vat - type: 'null' title: Tax Id organization_id: type: string format: uuid4 title: Organization Id description: The ID of the organization owning the customer. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 deleted_at: anyOf: - type: string format: date-time - type: 'null' title: Deleted At description: Timestamp for when the customer was soft deleted. members: items: $ref: '#/components/schemas/Member' type: array title: Members description: List of members belonging to this customer. avatar_url: type: string title: Avatar Url examples: - https://www.gravatar.com/avatar/xxx?d=404 type: object required: - id - created_at - modified_at - metadata - external_id - email - email_verified - name - billing_address - tax_id - organization_id - deleted_at - avatar_url title: CustomerWithMembers description: A customer in an organization with their members loaded. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AddressInput: properties: line1: anyOf: - type: string - type: 'null' title: Line1 line2: anyOf: - type: string - type: 'null' title: Line2 postal_code: anyOf: - type: string - type: 'null' title: Postal Code city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State country: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW title: CountryAlpha2Input examples: - US - SE - FR x-speakeasy-enums: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW type: object required: - country title: AddressInput CustomerType: type: string enum: - individual - team title: CustomerType OwnerCreate: properties: email: anyOf: - type: string format: email - type: 'null' title: Email description: The email address of the member. examples: - member@example.com name: anyOf: - type: string maxLength: 256 description: The name of the member. examples: - Jane Doe - type: 'null' title: Name external_id: anyOf: - type: string - type: 'null' title: External Id description: >- The ID of the member in your system. This must be unique within the customer. examples: - usr_1337 type: object title: OwnerCreate description: Schema for creating an owner member during customer creation. MetadataOutputType: additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object Address: properties: line1: anyOf: - type: string - type: 'null' title: Line1 line2: anyOf: - type: string - type: 'null' title: Line2 postal_code: anyOf: - type: string - type: 'null' title: Postal Code city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State country: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW title: CountryAlpha2 examples: - US - SE - FR x-speakeasy-enums: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW type: object required: - country title: Address Member: properties: id: type: string format: uuid4 title: Id description: The ID of the member. created_at: type: string format: date-time title: Created At description: Creation timestamp of the object. modified_at: anyOf: - type: string format: date-time - type: 'null' title: Modified At description: Last modification timestamp of the object. customer_id: type: string format: uuid4 title: Customer Id description: The ID of the customer this member belongs to. email: type: string title: Email description: The email address of the member. examples: - member@example.com name: anyOf: - type: string - type: 'null' title: Name description: The name of the member. examples: - Jane Doe external_id: anyOf: - type: string - type: 'null' title: External Id description: >- The ID of the member in your system. This must be unique within the customer. examples: - usr_1337 role: $ref: '#/components/schemas/MemberRole' description: The role of the member within the customer. examples: - owner type: object required: - id - created_at - modified_at - customer_id - email - name - external_id - role title: Member description: A member of a customer. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MemberRole: type: string enum: - owner - billing_manager - member title: MemberRole securitySchemes: access_token: type: http scheme: bearer description: >- You can generate an **Organization Access Token** from your organization's settings. ````