Skip to navigation
API Referencecustomers

Create a customer unit alias

Creates an alias that lands signals on this unit: a signal whose externalCustomerId is the alias resolves to this customer and, when it names no customerUnit, to this unit. The alias shares one set of ids with customer external ids and unit ids, unique within the organization and ignoring letter case: an alias another customer holds is refused with 409 EXTERNAL_ID_IN_USE. Use the value returned as customer.id, for example cus_abc123; if you have your own customer ID, use the /api/v2/customers/external/{externalId}/… twin.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Path parameters

idstringRequiredformat: "^cus_.+"
Paid customer display id
externalCustomerUnitIdstringRequired>=1 character

Your own id for the unit (its externalId), unique within this customer.

Request

Body
aliasstringRequired1-255 characters
Alternate external identifier that should resolve to this customer.
namestringOptional<=120 characters
Optional display name for this alias.
descriptionstringOptional<=500 characters
Optional note describing where this alias comes from.

Response

201
aliasstring
Alternate external identifier that resolves to the customer.
customerIdstring
Paid customer display ID this alias resolves to.
customerUnitExternalIdstring or null

Your id of the customer unit signals carrying this alias land on: the unit the alias was created under, or the customer's root unit for a customer-level alias. null only while the customer has no root unit.

namestring or null
descriptionstring or null
createdAtdatetime
updatedAtdatetime

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
500
Internal Server Error