openapi: 3.2.0
info:
  version: 1.3.35
  title: Versapay API Reference Customers API
  contact:
    name: Versapay Support
    url: https://www.versapay.com/support
    email: support@versapay.com
  x-logo:
    url: https://developers.versapay.com/images/logo.png
  termsOfService: https://www.versapay.com/terms-of-use
  license:
    name: Copyright 2022 Versapay. All Rights Reserved.
  description: 'As a supplier your customers are the entities that are invoiced.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a customer.

    '
servers:
- url: https://secure.versapay.com
  description: Production
- url: https://uat.versapay.com
  description: UAT
tags:
- name: Customers
  description: 'As a supplier your customers are the entities that are invoiced.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a customer.

    '
paths:
  /api/imports/customer:
    post:
      summary: Create and Update Customer
      description: 'Create a customer using the following attributes (at minimum by providing values for required attributes). If providing an identifier for an existing customer, its information is updated.<br><br>

        *Note: Any additional non-standard attribute will be stored with customer record and available for presentment rendering.*

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    example: C1234
                  message:
                    type: string
                    example: 1 customer with 3 contacts
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /api/exports/customer/{identifier}:
    get:
      summary: Export/View a Customer
      description: 'View a customer based on the `identifier` provided.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer record.

          '
        schema:
          type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /api/exports/customers:
    get:
      summary: Export Customers
      description: 'Customer records that have been created since watermark, limited to 100 records at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/CustomersResponse'
              examples:
                customers:
                  value:
                    customers:
                      '20':
                        identifier: megavoice-customer-1
                        display_number: megavoice-customer-1
                        name: MegavoiceCust
                        email: mukmuk@example.com
                        business_number: null
                        first_name: null
                        last_name: null
                        address_1: null
                        address_2: null
                        postal_code: null
                        city: null
                        province: null
                        country: ''
                        telephone: null
                        fax: null
                        status: ''
                        auto_debit: ''
                        invite_sent: null
                        signed_up: null
                        notification_suppressed: false
                        notification_override: false
                        paper_invoices: false
                        paper_statements: false
                        parent_identifier: null
                        balance_cents: 0
                        aging_cents: 0
                        aging_30_cents: 0
                        aging_60_cents: 0
                        aging_90_cents: 0
                        aging_120_cents: 0
                        aging_180_cents: 0
                        aging_older_cents: 0
                        current_cents: 0
                        credit_cents: 0
                        unapplied_payment_cents: 0
                        prepayment_cents: 0
                        owing_cents: 0
                        notes: null
                        adp: null
                        adp_arc: null
                        adp_external: null
                        last_contact_date: null
                        next_contact_date: null
                        credit_limit_cents: null
                        account_status: open
                        tags: null
                        user_tags: null
                        external_id: '1'
                        watermark: 20
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/customers/recent:
    get:
      summary: Export Customers Recently Updated
      description: 'Customer records that have been updated in the past 7 days, since watermark, limited to 100 records at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/CustomersResponse'
              examples:
                customers:
                  value:
                    customers:
                      '20':
                        identifier: megavoice-customer-1
                        display_number: megavoice-customer-1
                        name: MegavoiceCust
                        email: mukmuk@example.com
                        business_number: null
                        first_name: null
                        last_name: null
                        address_1: null
                        address_2: null
                        postal_code: null
                        city: null
                        province: null
                        country: ''
                        telephone: null
                        fax: null
                        status: ''
                        auto_debit: ''
                        invite_sent: null
                        signed_up: null
                        notification_suppressed: false
                        notification_override: false
                        paper_invoices: false
                        paper_statements: false
                        parent_identifier: null
                        balance_cents: 0
                        aging_cents: 0
                        aging_30_cents: 0
                        aging_60_cents: 0
                        aging_90_cents: 0
                        aging_120_cents: 0
                        aging_180_cents: 0
                        aging_older_cents: 0
                        current_cents: 0
                        credit_cents: 0
                        unapplied_payment_cents: 0
                        prepayment_cents: 0
                        owing_cents: 0
                        notes: null
                        adp: null
                        adp_arc: null
                        adp_external: null
                        last_contact_date: null
                        next_contact_date: null
                        credit_limit_cents: null
                        account_status: open
                        tags: null
                        user_tags: null
                        external_id: '1'
                        watermark: 20
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/customer/{identifier}/open_invoices:
    get:
      summary: Export Open Invoices for a Customer
      description: 'Invoice records with an open balance for the customer based on the `identifier` provided,

        limited to 100 records at a time.<br><br>A consumer should store the last `watermark` value of each

        response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer record.

          '
        schema:
          type: string
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    number:
                      type: string
                      description: Invoice number, unique within a supplier.
                    display_number:
                      type: string
                      description: Invoice number as displayed to customers.
                    currency:
                      type: string
                      description: Currency code, based on ISO-4217, in lowercase. E.g. `cad`, `usd`, `aud`
                    amount_cents:
                      type: integer
                      description: The invoice amount in cents.
                    owing_cents:
                      type: integer
                      description: Balance remaining on this invoice or credit memo.
                    customer_identifier:
                      type: string
                      description: Unique identifier for customer.
                    watermark:
                      $ref: '#/components/schemas/Watermark'
              example:
                open_invoices:
                - number: sh763-h3454-dh3432
                  display_number: INV1234
                  currency: usd
                  amount_cents: 40000
                  owing_cents: 30000
                  customer_identifier: CUS001
                  watermark: 8123612
                - number: pq7d2-h3124-jl3937
                  display_number: INV5678
                  currency: usd
                  amount_cents: -10000
                  owing_cents: -10000
                  customer_identifier: CUS001
                  watermark: 8123615
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /api/invitations:
    post:
      summary: Issue an invitation
      description: 'Issue a new contact invitation for the specified customer.  The recipient of the invitation will begin to receive other Collaborative AR notifications, subject to the configuration of the supplier.


        *Note:* If the provided email is not an existing contact of the specified customer, a new contact will be created.

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - email
              properties:
                identifier:
                  type: string
                  description: the `identifier` of the customer to invite the contact to
                  example: CUS001
                email:
                  type: string
                  description: Contact email address.
                  example: bob.smith@example.com
      responses:
        '200':
          description: Successfully Invited
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Cancel an invitation
      description: 'Cancel an existing contact invitation for the specified customer.


        *Note:* `403` will be returned if the specified customer is closed, or if the specified email was invited by a customer user

        '
      tags:
      - Customers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - email
              properties:
                identifier:
                  type: string
                  description: the `identifier` of the customer to cancel the invitation for
                  example: CUS001
                email:
                  type: string
                  description: Contact email address.
                  example: bob.smith@example.com
      responses:
        '200':
          description: Invitation Successfully Cancelled
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /api/imports/customers/{identifier}/update_identifier:
    post:
      summary: Update Customer Identifier
      description: 'Update a customer''s identifier and any associations where identifier is being stored. <br><br> *Note:* `412` will be returned if the specified customer cannot be found or the identifier has already been taken.

        '
      tags:
      - Customers
      parameters:
      - name: identifier
        in: path
        required: true
        description: '`identifier` of the customer to be updated.

          '
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
              - new_identifier
              properties:
                new_identifier:
                  type: string
                  description: Customer's new identifier to be used. Must be unique within supplier.
                  example: CUS-1001
      responses:
        '200':
          description: Customer Successfully Updated.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    description: Message indicating update successful.
                    example: customer identifier updated
                  identifier:
                    type: string
                    description: Customer's new identifier.
                    example: CUS-1001
        '412':
          description: Precondition failed.
          content:
            application/json:
              schema:
                properties:
                  importer:
                    type: string
                    description: stringified json message containing error.
                    example: '{:customer=>["not found."]}'
components:
  schemas:
    Contact:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          description: Email address of the contact.
          format: email
        first_name:
          type: string
          description: First name of the contact.
        last_name:
          type: string
          description: Last name of the contact.
        title:
          type: string
          description: Title of the contact.
        department:
          type: string
          description: Department of the contact.
        telephone:
          type: string
          description: Phone number of the contact.
        bulk_activate:
          type: boolean
          description: If this is `true`, the contact is activated or invited (depending on the account configuration) on import.
          default: false
    Customer:
      type: object
      required:
      - identifier
      - name
      properties:
        identifier:
          type: string
          description: Customer number, must be unique within supplier. Alphanumeric.
          example: C1234
        display_number:
          type: string
          description: Customer display number, Alphanumeric.
          example: DispNum1234
        name:
          type: string
          description: Customer name.
          example: Acme Inc.
        email:
          type: string
          format: email
          description: Email address of the default contact.
          example: bob.smith@example.com
        first_name:
          type: string
          description: First name of the default contact.
          example: Bob
        last_name:
          type: string
          description: Last name of the default contact.
          example: Smith
        notes:
          type: string
          description: Optional text field up to 64K.
          example: Payment terms will be revised next year.
        address_1:
          type: string
          description: Billing address line 1.
          example: 200 Main Street
        address_2:
          type: string
          description: Billing address line 2.
          example: Suite 250
        city:
          type: string
          description: Billing address - city.
          example: Toronto
        province:
          type: string
          description: Billing address - state or province.
          example: 'ON'
        postal_code:
          type: string
          description: Billing address - zip or postal code.
          example: M5M 5M5
        country:
          type: string
          description: Billing address - country.
          example: CA
        telephone:
          type: string
          description: Customer phone number.
          example: (416) 123-4567
        fax:
          type: string
          description: Customer fax number.
          example: (416) 100-1020
        url:
          type: string
          format: uri
          description: Customer web site.
          example: www.acmeinc.com
        business_number:
          type: string
          description: Customer EIN or Business Number. 20-character alphanumeric.
          example: GS324587987
        locale:
          type: string
          description: Customer language, based on ISO 639-1 standard.
          enum:
          - en
          - fr
          - es
        parent_identifier:
          type: string
          description: Required if the customer is part of a hierarchy, and this customer has a level (parent) above it. This is the identifier of the customer immediately above this customer in the tree.
          example: P3212
        pdf_attachment_opt_in:
          type: boolean
          description: If `true`, the customer will receive PDFs of invoices and attachments with all invoice notifications.
          default: false
        account_status:
          type: string
          description: The status of the customer's account with the supplier.
          enum:
          - open
          - closed
          default: open
        last_contact_date:
          type: string
          format: date
          description: The last time the customer was contacted. It is ignored if the customer already has a last contact date and it is more recent than this one.
          example: '2017-12-04'
        next_contact_date:
          type: string
          format: date
          description: The date of the next planned contact with the customer. This always overwrites what is on the customer.
          example: '2018-02-15'
        credit_limit_cents:
          type: integer
          description: The customer's credit limit. This is the maximum value of outstanding invoices before the supplier is alerted, if supplier is configured to monitor this. If the customer is a multi-currency customer, this is the total credit limit converted to a single currency (see next field.)
          example: '2000000'
        credit_limit_currency:
          type: string
          description: Currency of the credit limit. If blank, defaults to the currency of the majority of the customer's invoices. If there are no invoices, defaults to the supplier’s default currency.
          example: CAD
        credit_rating:
          type: string
          description: Credit rating for the customer.
          example: AA
        terms_type:
          type: string
          description: This field and `terms_value` specify how to set a customer's due date.
          enum:
          - date
          - day
        terms_value:
          type: integer
          description: 'This field and `terms_type` specify how to set a customer''s invoice due date.


            If terms_type is ''day'':


            * It means the due date should be <terms_value> days after invoice date.

            * E.g. if terms_value is 30, the due date must be 30 days after the invoice date.

            * It must be a whole number between 0 and 100.


            If terms_type is ''date'':


            * It means the due date is on a fixed day (terms_value) of the month.

            * E.g. if terms_value is 15, it means the due date should be on the 15th of the month after invoice date.

            * It must be an integer between 1 and 27 inclusive, or -1 to specify the last day of the month, or -2 to specify the second-last day of the month.

            '
          example: 15
        company_bio:
          type: string
          description: Short description of products and services that the customer offers.
          example: Acme Inc. sells cutting-edge widgets.
        ignores_cc_payment_rules:
          type: boolean
          description: If this is `true`, it means that the customer is not subject to any credit card payment rules, and is free to use credit cards any time.
          default: false
          example: 'false'
        notification_suppressed:
          type: boolean
          description: If this is `true`, all notifications to the customer are suppressed.
          default: false
          example: 'false'
        tags:
          type: string
          description: One or more tags separated by semi-colons.
          example: Blue;Green;Yellow
        external_id:
          type: string
          description: External (ERP-based) identifier for the customer record.
        external_group_identifier:
          type: string
          description: 'External (ERP-based) identifier used to control customer grouping.


            If the supplier is configured for restricted grouping, the system will not permit a user to group customers together that have different values for `external_group_identifier`.


            If the supplier is not configured for restricted grouping, this value is saved but ignored.

            '
        replace_contacts:
          type: boolean
          description: When `true` for a customer that is re-imported any contacts in the payload that are also in the DB will be updated if they are not signed-up users, and any contacts in the DB that were created by the supplier and are not in the payload will be deleted if not signed up, otherwise they will be disabled.
          default: false
        line_item_attributes:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
          example:
          - email: jane.smith@example.com
            first_name: Jane
            last_name: Smith
            telephone: 809-888-1234
            title: Buyer
          - email: bob.smith@example.com
            first_name: Bob
            last_name: Smith
            title: Manager
            department: Accounts Payable
            telephone: 809-345-9833
          - email: steve.jobs@example.com
            first_name: Steve
            last_name: Jobs
            title: CEO
    CustomerResponse:
      type: object
      properties:
        identifier:
          type: string
          description: Customer number, unique within supplier.
          example: CUST-001
        name:
          type: string
          description: Customer name.
          example: ABC Inc.
        email:
          type: string
          format: email
          description: Email address of the default contact.
          example: bob.smith@example.com
        first_name:
          type: string
          description: First name of the default contact.
          example: Bob
        last_name:
          type: string
          description: Last name of the default contact.
          example: Smith
        notes:
          type: string
          description: Optional text field up to 64K.
          example: Payment terms will be revised next year.
        address_1:
          type: string
          description: Billing address line 1.
          example: 1 Bay St.
        address_2:
          type: string
          description: Billing address line 2.
          example: Suite 200
        city:
          type: string
          description: Billing address - city.
          example: Toronto
        province:
          type: string
          description: Billing address - state or province.
          example: 'ON'
        postal_code:
          type: string
          description: Billing address - zip or postal code.
          example: M5M 5M5
        country:
          type: string
          description: Billing address - country.
          example: CA
        telephone:
          type: string
          description: Customer phone number.
          example: (416) 123-4567
        fax:
          type: string
          description: Customer fax number.
          example: (416) 111-2222
        business_number:
          type: string
          description: Customer EIN or Business Number. 20-character alphanumeric.
          example: '18889990'
        status:
          type: string
          description: Customer adoption status.
          enum:
          - Not Activated
          - Activated
          - Invited
          - Express
          - Signed Up
          - Paying
        auto_debit:
          type: string
          description: '`Y`, if customer has set up an AutoPay agreement. `N` otherwise.

            '
          enum:
          - Y
          - N
          example: N
        invite_sent:
          type: string
          format: date
          description: The date when invite was sent, in YYYY-MM-DD format.
          example: '2018-02-23'
        signed_up:
          type: string
          format: date
          description: The date when customer user signed up, in YYYY-MM-DD format.
          example: '2018-02-24'
        notification_suppressed:
          type: string
          description: '`Y`, if notifications are suppressed for the customer. `N` otherwise.

            '
          enum:
          - Y
          - N
        notification_override:
          type: string
          description: '`Y`, if overdue balance notifications are made optional for the customer. `N` otherwise.

            '
          enum:
          - Y
          - N
        paper_invoices:
          type: string
          description: '`Y`, if customer receives paper invoices. `N` otherwise.

            '
          enum:
          - Y
          - N
        balance:
          type: string
          description: 'Total outstanding balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_balance`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        credit:
          type: string
          description: 'Total outstanding credit balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_credit`). This applies to suppliers accepting multicurrency payments.

            '
          example: -$123.45
        current:
          type: string
          description: 'Current outstanding balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_current`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging:
          type: string
          description: 'Total overdue balance on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_30:
          type: string
          description: 'Balance overdue (1-30 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_30`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_60:
          type: string
          description: 'Balance overdue (31-60 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_60`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_90:
          type: string
          description: 'Balance overdue (61-90 days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_90`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        aging_older:
          type: string
          description: 'Balance overdue (91+ days) on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_aging_older`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        unapplied_payment:
          type: string
          description: 'Total unapplied payment on the customer account.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_unapplied_payment`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_current:
          type: string
          description: 'Total outstanding balance of invoices opened this month on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_current`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_prior_1:
          type: string
          description: 'Total outstanding balance of invoices opened 1 month ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_prior_1`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_prior_2:
          type: string
          description: 'Total outstanding balance of invoices opened 2 months ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_prior_2`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_prior_3:
          type: string
          description: 'Total outstanding balance of invoices opened 3 months ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_prior_3`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_prior_4:
          type: string
          description: 'Total outstanding balance of invoices opened 4 months ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_prior_4`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_prior_5:
          type: string
          description: 'Total outstanding balance of invoices opened 5 months ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_prior_5`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        monthly_balance_older:
          type: string
          description: 'Total outstanding balance of invoices opened 6 or more months ago on the customer account.<br>


            Note: This applies to suppliers configured for monthly balance aging.<br>


            Note: This field is prefixed with the currency code, for each currency the customer is transacting in (say, `usd_monthly_balance_older`). This applies to suppliers accepting multicurrency payments.

            '
          example: $123.45
        adp:
          type: string
          description: Average days to pay.
          example: '100'
        adp_arc:
          type: string
          description: Average days to pay.
          example: '100'
        adp_external:
          type: string
          description: Average days to pay, outside Versapay.
          example: '100'
        last_contact_date:
          type: string
          format: date
          description: The last time the customer was contacted.
          example: '2017-12-04'
        next_contact_date:
          type: string
          format: date
          description: The date of the next planned contact with the customer.
          example: '2018-02-15'
        credit_limit:
          type: string
          description: The customer's credit limit. If the customer is a multi-currency customer, this is the total credit limit converted to a single currency.
          example: $2000.00
        oldest_open_invoice:
          type: string
          description: Oldest outstanding invoice number.
          example: INV-00101
        oldest_open_invoice_age:
          type: string
          description: Age (in days) of the oldest outstanding invoice.
          example: '31'
        oldest_open_invoice_balance:
          type: string
          description: Balance of the oldest outstanding invoice.
          example: $123.45
        last_payment_date:
          type: string
          format: date
          description: Date when the last payment was made, in YYYY-MM-DD format.
          example: '2018-01-31'
        last_payment_amount:
          type: string
          description: Amount of the last payment.
          example: $123.45
        last_payment_source:
          type: string
          description: Source of the last payment.
          example: arc
          enum:
          - arc
          - external
          - erp
          - manual
        account_status:
          type: string
          description: The status of the customer's account with the supplier.
          enum:
          - open
          - closed
        tags:
          type: string
          description: Semi-colon delimited list of tags imported from ERP on the customer account.
          example: Blue;Green;Yellow
        user_tags:
          type: string
          description: Semi-colon delimited list of tags assigned via Portal on the customer account.
          example: Gold;Silver;Bronze
        divisions_names:
          type: string
          description: Names of divisions the customer belongs to, separated by semi-colons.
          example: North;South;East
        divisions_codes:
          type: string
          description: Codes of divisions the customer belongs to, separated by semi-colons.
          example: 010;020;050
        url:
          type: string
          description: The URL to the customer details page in Collaborative AR.
          example: https://secure.versapay.com/receivables/customers/10917589
        group_id:
          type: string
          description: When a value is present, this customer is part of a group.  Customers sharing this value are grouped together.
        external_group_identifier:
          type: string
          description: External (ERP-based) identifier used to control customer grouping.
        display_number:
          type: string
          description: Customer display number.
          example: CUST-DN-001
        root_identifier:
          type: string
          description: The root identifier within the hierarchy if the customer is part of a hierarchy. Otherwise it is the customer identifier itself.
          example: P0900
        contacts:
          type: array
          description: Contacts (and/or corresponding signed up user profile information)
          items:
            type: object
            properties:
              email:
                type: string
                description: Email address of the contact.
                format: email
              first_name:
                type: string
                description: First name of the contact.
              last_name:
                type: string
                description: Last name of the contact.
              telephone:
                type: string
                description: Phone number of the contact.
              title:
                type: string
                description: Title of the contact.
              department:
                type: string
                description: Department of the contact.
              activated_at:
                type: string
                format: date
                description: Date contact was activated
              invited_at:
                type: string
                format: date
                description: Date contact was invited for user access
              login_at:
                type: string
                format: date
                description: Date user last signed in as user
              user_first_name:
                type: string
                description: First name set on associated user profile
              user_last_name:
                type: string
                description: Last name set on associated user profile
              user_role:
                type: string
                description: Access role for user
              user_telephone:
                type: string
                description: Telephone set on associated user profile
              user_title:
                type: string
                description: Title set on associated user profile
              user_department:
                type: string
                description: Department set on associated user profile
      example:
        identifier: '163627'
        name: 21st Century Media
        business_number: ''
        first_name: ''
        last_name: ''
        email: customer+21st@versapay.com
        address_1: ''
        address_2: ''
        postal_code: ''
        city: ''
        province: ''
        country: ''
        telephone: ''
        fax: ''
        status: Signed Up
        auto_debit: N
        invite_sent: '2016-03-29'
        signed_up: '2016-03-29'
        notification_suppressed: N
        notification_override: N
        paper_invoices: N
        paper_statements: N
        balance: $26,185.00
        credit: $0.00
        current: $0.00
        unapplied_payment: $0.00
        aging: $26,185.00
        aging_30: $0.00
        aging_60: $0.00
        aging_90: $0.00
        aging_older: $26,185.00
        notes: ''
        parent_identifier: '161803'
        parent_name: Digital First Media
        parent_email: customer+dfm@versapay.com
        adp: ''
        adp_arc: ''
        adp_external: ''
        last_contact_date: ''
        next_contact_date: ''
        credit_limit: $0.00
        oldest_open_invoice: '5557488'
        oldest_open_invoice_age: '1726'
        oldest_open_invoice_balance: $1,325.00
        last_payment_date: ''
        last_payment_amount: $0.00
        last_payment_source: ''
        account_status: open
        tags: ''
        user_tags: A+ Customer;Tester A;91+ $2500+ Test Tag
        divisions_names: ''
        divisions_codes: ''
        url: https://secure.versapay.com/receivables/customers/10917589
        group_id: ''
        external_group_identifier: ''
        credit_card_fee_exempt: N
        auto_update_cc_expiry: N
        cash_on_delivery: N
        watermark: 10917589
        root_identifier: P0900
        contacts:
        - email: customer+21st@versapay.com
          first_name: null
          last_name: null
          telephone: null
          title: null
          department: null
          activated_at: '2016-03-29T18:41:19.000Z'
          invited_at: '2016-03-29T18:41:19.000Z'
          login_at: '2016-05-19T19:03:07.000Z'
          user_first_name: null
          user_last_name: null
          user_role: admin
          user_telephone: null
          user_title: null
          user_department: null
        - email: dteets@21st-centurymedia.com
          first_name: null
          last_name: null
          telephone: null
          title: null
          department: null
          activated_at: null
          invited_at: null
          login_at: null
          user_first_name: null
          user_last_name: null
          user_role: null
          user_telephone: null
          user_title: null
          user_department: null
    Watermark:
      type: integer
      format: int64
      example: 0
    CustomersResponse:
      type: object
      properties:
        identifier:
          type: string
          description: Customer number, unique within supplier.
        display_number:
          type: string
          description: Customer display number.
        name:
          type: string
          description: Customer name.
        email:
          type: string
          format: email
          description: Email address of the default contact.
        business_number:
          type: string
          description: Customer EIN or Business Number.
        first_name:
          type: string
          description: First name of the default contact.
        last_name:
          type: string
          description: Last name of the default contact.
        address_1:
          type: string
          description: Billing address line 1.
        address_2:
          type: string
          description: Billing address line 2.
        postal_code:
          type: string
          description: Billing address - zip or postal code.
        city:
          type: string
          description: Billing address - city.
        province:
          type: string
          description: Billing address - state or province.
        country:
          type: string
          description: Billing address - country.
        telephone:
          type: string
          description: Customer phone number.
        fax:
          type: string
          description: Customer fax number.
        status:
          type: string
          description: Customer adoption status.
        auto_debit:
          type: string
          description: AutoPay agreement status.
        invite_sent:
          type: string
          format: date
          description: The date when invite was sent, in YYYY-MM-DD format.
        signed_up:
          type: string
          format: date
          description: The date when customer user signed up, in YYYY-MM-DD format.
        notification_suppressed:
          type: boolean
          description: If true, notifications to the customer are suppressed.
        notification_override:
          type: boolean
          description: If true, overdue balance notifications are made optional.
        paper_invoices:
          type: boolean
          description: If true, customer receives paper invoices.
        paper_statements:
          type: boolean
          description: If true, customer receives paper statements.
        parent_identifier:
          type: string
          description: Identifier of the parent customer in a hierarchy.
        balance_cents:
          type: integer
          description: 'Total outstanding balance on the customer account in cents.

            '
        aging_cents:
          type: integer
          description: 'Total overdue balance on the customer account in cents.

            '
        aging_30_cents:
          type: integer
          description: 'Balance overdue (1-30 days) on the customer account in cents.

            '
        aging_60_cents:
          type: integer
          description: 'Balance overdue (31-60 days) on the customer account in cents.

            '
        aging_90_cents:
          type: integer
          description: 'Balance overdue (61-90 days) on the customer account in cents.

            '
        aging_120_cents:
          type: integer
          description: 'Balance overdue (91-120 days) on the customer account in cents.

            '
        aging_180_cents:
          type: integer
          description: 'Balance overdue (121-180 days) on the customer account in cents.

            '
        aging_older_cents:
          type: integer
          description: 'Balance overdue (181+ days) on the customer account in cents.

            '
        current_cents:
          type: integer
          description: 'Current outstanding balance in cents.

            '
        credit_cents:
          type: integer
          description: 'Total outstanding credit balance on the customer account in cents.

            '
        unapplied_payment_cents:
          type: integer
          description: 'Total unapplied payment on the customer account in cents.

            '
        prepayment_cents:
          type: integer
          description: 'Total prepayment on the customer account in cents.

            '
        owing_cents:
          type: integer
          description: Total owing balance in cents.
        notes:
          type: string
          description: Optional notes.
        adp:
          type: string
          description: Average days to pay.
        adp_arc:
          type: string
          description: Average days to pay (checkout).
        adp_external:
          type: string
          description: Average days to pay (external).
        last_contact_date:
          type: string
          format: date
          description: Last contact date.
        next_contact_date:
          type: string
          format: date
          description: Next planned contact date.
        credit_limit_cents:
          type: integer
          description: Credit limit in cents.
        account_status:
          type: string
          description: Account status (open/closed).
        tags:
          type: string
          description: Semi-colon delimited list of imported tags.
        user_tags:
          type: string
          description: Semi-colon delimited list of user-assigned tags.
        attributes_marshal:
          type: object
          description: Additional attributes.
        external_id:
          type: string
          description: External (ERP-based) identifier for the customer record.
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
                example: This request is not allowed for this resource.
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
                example: You have not provided all necessary parameters to make this call.
    NotFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
                example: ActiveRecord::RecordNotFound
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
                example: API token does not have permission for this request. Please contact your account administrator.
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
                example: You need to sign in or create an account before continuing.
x-tagGroups:
- name: Versapay API
  description: Introduction to the Versapay API.
  tags:
  - Overview
  - Versioning & Compatibility
  - Environments
  - Rate Limits
  - Authentication
  - Webhooks
  - Watermark & Limit
- name: Collaborative AR
  description: Operations available for Collaborative AR integration.
  tags:
  - Reference Data
  - Onboarding
  - Ecommerce Integration
  - Orders
  - Order Transactions
  - Testing Order Transactions
  - Gift Cards
  - Card Present EMV
  - Settlement Reporting
  - Wallets
  - Customers
  - Invoices
  - Autopay
  - Invoicing Payments
  - Divisions
  - Notifications
  - Collaboration
  - File Imports