Dojo Customers API

openapi: 3.2.0
info:
  title: Dojo Customers API
  version: '2026-02-27'
  description: '# Introduction


    The Dojo API is a REST API, using HTTP response codes to convey status, including successful responses and errors.'
  termsOfService: https://dojo.tech/legal/
  contact:
    name: Dojo Developer Experience Team
servers:
- url: https://api.dojo.tech
security:
- ApiKeyAuth: []
tags:
- name: Customers
  description: Allows to create and manage a customer of your business.
paths:
  /customers:
    post:
      tags:
      - Customers
      operationId: Customers_Create
      summary: Create a customer
      description: Creates a new customer.
      parameters:
      - $ref: '#/components/parameters/VersionCustomers'
      requestBody:
        x-name: obj
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            example:
              name: Alex
              emailAddress: alex@dojo.com
        required: true
        x-position: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerFull'
              example:
                id: cust_sandbox_MJj8Flgfik25x47R4LFbxQ
                name: Alex
                emailAddress: alex@dojo.com
                createdAt: '2024-02-15T02:46:21.8232496Z'
                updatedAt: '2024-02-15T02:46:21.8232496Z'
                documentVersion: 0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /customers/{customerId}:
    delete:
      tags:
      - Customers
      operationId: Customers_Delete
      summary: Delete a customer
      description: Deletes a customer.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        x-position: 2
        example: cust_qNkU6yob0vOMxUlb2oynUw
        description: The unique identifier of the customer.
      - $ref: '#/components/parameters/VersionCustomers'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    patch:
      tags:
      - Customers
      operationId: Customers_Update
      summary: Update information about a customer
      description: Updates information about a customer.
      parameters:
      - name: customerId
        in: path
        required: true
        example: cs_qNkU6yob0vOMxUlb2oynUw
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        description: The unique identifier of the customer.
        x-position: 2
      - $ref: '#/components/parameters/VersionCustomers'
      requestBody:
        x-name: updateData
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerFull'
              example:
                id: cs_qNkU6yob0vOMxUlb2oynUw
                name: Alex
                emailAddress: alex@dojo.com
                phoneNumber: 078976534161
                documentVersion: 1
                createdAt: '2023-08-24T14:15:22Z'
                updatedAt: '2023-09-24T14:15:22Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
      - Customers
      operationId: Customers_Get
      summary: Retrieve a customer
      description: Retrieves the details of a customer.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        description: Unique identifiers for the customers you want to get information about, separated by commas.
      - $ref: '#/components/parameters/VersionCustomers'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerFull'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /customers/{customerId}/create-secret:
    post:
      tags:
      - Customers
      operationId: Customers_CreateCustomerSecret
      summary: Create a customer secret
      description: Creates a unique customer secret key valid within a scope of time.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        x-position: 1
        example: cust_qNkU6yob0vOMxUlb2oynUw
        description: The unique identifier of the customer.
      - $ref: '#/components/parameters/VersionCustomers'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSecret'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /customers/public/{customerId}/payment-methods:
    get:
      tags:
      - Customers
      operationId: Customers_GetPaymentMethods
      summary: Retrieve payment method
      description: Retrieves available payment methods for a customer.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        x-position: 1
        example: cust_qNkU6yob0vOMxUlb2oynUw
        description: The unique identifier of the customer.
      - $ref: '#/components/parameters/VersionCustomers'
      - name: authorization
        in: header
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 500
        x-position: 3
        example: 'Authorization: Basic cs_generated-customer-secret'
        description: 'Basic HTTP authentication to grant access to customer-owned resources.


          - The required customer secret key is short-lived and will expire after a pre-configured set of time.

          - The customer secret can be generated by calling [POST /customers/{`customerId`}/create-secret](#operation/Customers_CreateCustomerSecret)

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPaymentMethods'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /customers/public/{customerId}/payment-methods/{paymentMethodId}:
    delete:
      tags:
      - Customers
      operationId: Customers_DeletePaymentMethod
      summary: Remove payment method
      description: Delete a customer payment method.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        x-position: 1
        example: cust_qNkU6yob0vOMxUlb2oynUw
        description: The unique identifier of the customer.
      - name: paymentMethodId
        in: path
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        x-position: 2
        example: pm_otRL98WURbaAKs0sdy7_5w
        description: The unique identifier of the customer payment method.
      - $ref: '#/components/parameters/VersionCustomers'
      - name: authorization
        in: header
        required: true
        schema:
          type:
          - string
          - 'null'
          maxLength: 500
        x-position: 4
        example: 'Authorization: Basic cs_generated-customer-secret'
        description: 'Basic HTTP authentication to grant access to customer-owned resources.


          - The required customer secret key is short-lived and will expire after a pre-configured set of time.

          - The customer secret can be generated by calling [POST /customers/{`customerId`}/create-secret](#operation/Customers_CreateCustomerSecret)

          '
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /customers/search:
    post:
      tags:
      - Customers
      operationId: Customers_Search
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCustomerRequest'
        required: true
        x-position: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfCustomer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      parameters:
      - $ref: '#/components/parameters/VersionCustomers'
      summary: List all customers
      description: 'Retrieves a list of customers.

        Results are paginated. By default, the method returns up to 50 customers.'
components:
  schemas:
    ProblemDetails:
      type: object
      description: Dojo follows the error response format proposed in [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807), also known as Problem Details for HTTP APIs.
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) that identifies the problem type.
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the error.
        status:
          type:
          - integer
          - 'null'
          format: int32
          description: The [HTTP status code](#section/Introduction/HTTP-Responses).
        detail:
          type:
          - string
          - 'null'
          description: An optional, human-readable message giving more details about the error.
        instance:
          type:
          - string
          - 'null'
          description: The URI reference of the problem.
        extensions:
          type: object
          description: This field names any extension methods that have been configured to help handle errors handling functionality.
          additionalProperties: {}
    CustomerSecret:
      type: object
      additionalProperties: false
      properties:
        secret:
          type:
          - string
          - 'null'
          description: The unique identifier for the secret.
        createdAt:
          type: string
          format: date-time
          description: 'The creation date, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format.

            '
        expireAt:
          type: string
          format: date-time
          description: 'The timestamp at which the customer secret expires, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format.

            '
      example:
        secret: cs_qNkU6yob0vOMxUlb2oynUw
        createdAt: '2022-10-31T10:15:00Z'
        expireAt: '2022-10-31T10:30:22Z'
    Address:
      type: object
      additionalProperties: false
      example:
        address1: The Brunel Building
        address2: 2 Canalside Walk
        city: London
        postcode: W2 1DG
        countryCode: GB
        county: UK
      description: Details about the address.
      properties:
        address1:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Address line 1 (for example, company name).
        address2:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Address line 2 (for example, street, apartment, or suite).
        address3:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Address line 3.
        address4:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Address line 4.
        city:
          type:
          - string
          - 'null'
          maxLength: 100
          description: City, town, district, suburb, or village.
          example: London
        state:
          type:
          - string
          - 'null'
          maxLength: 100
          description: State, province, or region.
        postcode:
          type:
          - string
          - 'null'
          maxLength: 50
          description: ZIP or postal code.
        countryCode:
          type: string
          maxLength: 10
          description: 'Two-letter country code in [ISO 3166–1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.

            '
          example: GB
        locality:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Locality, can use in addition to city.
        county:
          type:
          - string
          - 'null'
          maxLength: 100
          description: County or zone.
      required:
      - countryCode
    CustomerPaymentMethods:
      type: object
      additionalProperties: false
      properties:
        customerId:
          type:
          - string
          - 'null'
          description: The unique identifier of the customer.
        merchantId:
          type:
          - string
          - 'null'
          description: A unique identifier for the merchant. A single merchant can be associated with multiple terminals, point-of-sale machines, and waiters.
        savedPaymentMethods:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomerPaymentMethod'
          description: List of the customer saved payment methods.
        supportedPaymentMethods:
          oneOf:
          - $ref: '#/components/schemas/SupportedPaymentMethods'
          description: Supported payment methods.
      example:
        customerId: cust_qNkU6yob0vOMxUlb2oy123
        merchantId: '123456789'
        savedPaymentMethods:
        - id: pm_12345
          cardDetails:
            pan: 52000000****0056
            expiryDate: '2024-12-31'
            scheme: MASTERCARD
        supportedPaymentMethods:
          cardSchemes:
          - VISA
          - MASTERCARD
          - MAESTRO
          - DISCOVER
          - DCI
          - AMEX
          wallets:
          - APPLE_PAY
          - GOOGLE_PAY
    CustomerPaymentMethod:
      type: object
      additionalProperties: false
      properties:
        id:
          type:
          - string
          - 'null'
          description: The unique identifier of the customer's saved payment method.
        cardDetails:
          description: The card details saved by the customer.
          oneOf:
          - $ref: '#/components/schemas/CardDetails'
    UpdateCustomerRequest:
      type: object
      additionalProperties: false
      example:
        phoneNumber: 078976534161
      properties:
        name:
          type:
          - string
          - 'null'
          description: The customer's name.
        billingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's invoicing address.
        shippingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's shipping address.
        emailAddress:
          type:
          - string
          - 'null'
          description: The customer's email address.
        phoneNumber:
          type:
          - string
          - 'null'
          description: The customer's phone number.
        vatNumber:
          type:
          - string
          - 'null'
          description: The customer's VAT number.
    CardDetails:
      type: object
      properties:
        pan:
          description: 'The masked primary account number (PAN) of the customer''s saved card.

            '
          type: string
        expiryDate:
          description: The expiry date of the card saved by the customer.
          type: string
        scheme:
          $ref: '#/components/schemas/CardScheme'
      additionalProperties: false
    SearchCustomerRequest:
      type: object
      additionalProperties: false
      description: 'A cursor for use in pagination. '
      properties:
        limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          example: 20
          default: 50
          description: The maximum number of results to be returned in a single page.
        before:
          type:
          - string
          - 'null'
          maxLength: 200
          description: A cursor for use in pagination for the previous page. `before` and `after` are mutually exclusive. Only one of these may be used.
        after:
          type:
          - string
          - 'null'
          maxLength: 200
          description: 'A cursor for use in pagination for the next page. `before` and `after` are mutually exclusive. Only one of these may be used.

            '
    WalletPaymentOption:
      type: string
      description: Wallet payment options (e.g., Apple Pay, Google Pay).
    CardScheme:
      description: Supported card schemes (VISA, MASTERCARD, MAESTRO, DISCOVER, DCI, AMEX)
      type: string
    CustomerFull:
      type: object
      additionalProperties: false
      example:
        id: cs_qNkU6yob0vOMxUlb2oynUw
        name: Alex
        emailAddress: alex@dojo.com
        documentVersion: 0
        createdAt: '2023-08-24T14:15:22Z'
      properties:
        id:
          type:
          - string
          - 'null'
          description: The unique identifier of the customer.
        name:
          type:
          - string
          - 'null'
          description: The customer's name.
        shippingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's shipping address.
        billingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's invoicing address.
        emailAddress:
          type:
          - string
          - 'null'
          description: The customer's email address.
        phoneNumber:
          type:
          - string
          - 'null'
          description: The customer's phone number.
        vatNumber:
          type:
          - string
          - 'null'
          description: The customer's VAT number.
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
          description: 'The creation date, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format.

            '
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp of the update date, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format.
        documentVersion:
          type: integer
          format: int32
          description: The version of the customer's data updated with every change.
    PagedResultOfCustomer:
      type: object
      additionalProperties: false
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomerFull'
          description: An array of customers.
        before:
          type:
          - string
          - 'null'
          example: IjIwMjItMDYtMjJUMTQ6MTc6MjYuMDkyWiI=
          description: A cursor for use in pagination for the previous page.
        after:
          type:
          - string
          - 'null'
          example: IjIwMjItMDYtMjBUMTM6MzI6MjIuNDM1WiI=
          description: A cursor for use in pagination for the next page.
    SupportedPaymentMethods:
      type: object
      additionalProperties: false
      properties:
        cardSchemes:
          type:
          - array
          - 'null'
          description: Supported card schemes.
          items:
            $ref: '#/components/schemas/CardScheme'
        wallets:
          type:
          - array
          - 'null'
          description: List of supported payment wallets.
          items:
            $ref: '#/components/schemas/WalletPaymentOption'
    CreateCustomerRequest:
      type: object
      additionalProperties: false
      example:
        name: Alex
        emailAddress: alex@dojo.com
      properties:
        name:
          type:
          - string
          - 'null'
          maxLength: 100
          description: The customer's name.
        shippingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's shipping address.
        billingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address'
          description: The recipient's invoicing address.
        emailAddress:
          type:
          - string
          - 'null'
          maxLength: 254
          description: The customer's email address.
        phoneNumber:
          maxLength: 50
          minLength: 5
          type:
          - string
          - 'null'
          description: The customer's phone number.
        vatNumber:
          type:
          - string
          - 'null'
          maxLength: 50
          description: The customer's VAT number.
  parameters:
    VersionCustomers:
      name: version
      in: header
      required: true
      schema:
        type:
        - string
        - 'null'
      example: '2026-02-27'
      description: The API version with format yyyy-mm-dd. The current version is `2026-02-27`.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
x-tagGroups:
- name: Core payments
  tags:
  - Payment intents
  - Refunds
  - Reversal
  - Captures
  - Webhooks
  - Customers
  - Setup intents
- name: In-person payments
  tags:
  - Terminals
  - Terminal sessions
- name: Capabilities
  tags:
  - Capabilities
  - Events