openapi: 3.2.0
info:
  title: (Deprecated) Billing Agreements API
  version: 1.0.0
servers:
- url: https://global-api-sandbox.afterpay.com
  description: Sandbox
- url: https://global-api.afterpay.com
  description: Production
tags:
- name: Billing Agreements
paths:
  /v2/billing-agreements/approvals:
    post:
      operationId: start-billing-agreement-approval
      summary: Start Billing Agreement Approval Process
      description: 'Initiates the approval process for a new billing agreement.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: The consumer approved the billing agreement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementApprovalResponse'
        '401':
          description: 'Authentication failed or insufficient permissions.


            | errorCode | Description |

            | --- | --- |

            | unauthorized | The API credentials are invalid or missing. |

            | insufficient_permissions | The merchant lacks the required ''merchant_api_v2/initiate'' permission. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_object | One or more required fields in the request body were missing or invalid. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The billing agreement approval request details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingAgreementApprovalRequest'
  /v2/billing-agreements:
    post:
      operationId: create-billing-agreement
      summary: Create Billing Agreement
      description: 'Creates a new billing agreement from an order token.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Billing agreement created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            | headless_billing_agreement_not_authorised | Headless flow is not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '412':
          description: '| errorCode | Description |

            | --- | --- |

            | consumer_ineligible | Consumer not eligible |

            '
          content:
            application/json:
              schema:
                description: Any type
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the details needed to create a billing agreement
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgreementRequest'
  /v2/billing-agreements/alias:
    post:
      operationId: alias-billing-agreement
      summary: Create Billing Agreement Alias
      description: 'Creates an alias for an existing billing agreement to help load payment schedule widget.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Alias created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementAliasResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the billing agreement token and optional duration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingAgreementAliasRequest'
  /v2/billing-agreements/cancel:
    put:
      operationId: cancel-billing-agreement-alt
      summary: Cancel Billing Agreement (Alternative)
      description: 'Alternative endpoint to cancel a billing agreement using a request body instead of path parameter.

        Functionally equivalent to DELETE /v2/billing-agreements/{token}.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Billing agreement cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_found | The specified billing agreement token was not found. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the billing agreement token to cancel
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBillingAgreementRequest'
  /v2/billing-agreements/offers:
    post:
      operationId: retrieve-billing-agreement-offers
      summary: Retrieve Billing Agreement Offers
      description: 'Retrieves available offers for billing agreements based on amount and frequency.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Offers retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffersResponse'
        '401':
          description: 'Authentication failed or insufficient permissions.


            | errorCode | Description |

            | --- | --- |

            | unauthorized | The API credentials are invalid or missing. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_object | One or more required fields in the request body were missing or invalid. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the amount and billing agreement token to check offers for
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OffersRequest'
  /v2/billing-agreements/retrieve:
    post:
      operationId: retrieve-billing-agreement
      summary: Retrieve Billing Agreement
      description: 'Alternative endpoint to retrieve billing agreement details using a request body instead of path parameter.

        Functionally equivalent to GET /v2/billing-agreements/{token}.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Billing agreement details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_found | The specified billing agreement token was not found. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the billing agreement token to retrieve
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBillingAgreementRequest'
  /v2/billing-agreements/start:
    post:
      operationId: start-billing-agreement-link
      summary: Start Billing Agreement Link Flow
      description: 'Initiates the headless billing agreement link flow process.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '201':
          description: Link flow started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkStartResponse'
        '404':
          description: '| errorCode | Description |

            | --- | --- |

            | not_found | Afterpay consumer account does not exist |

            '
          content:
            application/json:
              schema:
                description: Any type
        '412':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_state | Failed to send code |

            '
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: '| errorCode | Description |

            | --- | --- |

            | too_many_requests | Too many requests |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the details needed to start the billing agreement link flow
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkStartRequest'
  /v2/billing-agreements/{token}:
    get:
      operationId: get-billing-agreement
      summary: Get Billing Agreement Details
      description: 'Retrieves the details of a billing agreement using its token.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: token
        in: path
        description: The unique identifier token of the billing agreement to retrieve
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Billing agreement details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_found | The specified billing agreement token was not found. |

            '
          content:
            application/json:
              schema:
                description: Any type
    delete:
      operationId: cancel-billing-agreement
      summary: Cancel Billing Agreement
      description: 'Cancels an existing billing agreement using its token.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Billing Agreements
      parameters:
      - name: token
        in: path
        description: The unique identifier token of the billing agreement to cancel
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Billing agreement cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAgreementResponse'
        '403':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_authorised | Recurring payments are not enabled for this merchant. |

            '
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: '| errorCode | Description |

            | --- | --- |

            | billing_agreement_not_found | The specified billing agreement token was not found. |

            '
          content:
            application/json:
              schema:
                description: Any type
components:
  schemas:
    CreateAgreementRequest:
      type: object
      properties:
        requestId:
          type: string
          description: A unique request ID, required for idempotent retries. It is recommended that the merchant generate a UUID for each unique request.
        token:
          type: string
          description: The token returned from the create approval request.
        merchantReference:
          type: string
          description: 'The reference order id that this payment corresponds to in the merchant''s system.

            Note: Providing a new value will update any value previously set in the Create Checkout request.'
      required:
      - token
      title: CreateAgreementRequest
    ConsumerOffers:
      type: object
      properties:
        noPaymentUpfront:
          $ref: '#/components/schemas/ConsumerOffersNoPaymentUpfront'
          description: Information about the no payment upfront feature eligibility
      description: Consumer offers
      title: ConsumerOffers
    Money:
      type: object
      properties:
        amount:
          type: string
          description: The amount as a string representation of a decimal number, rounded to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
      - amount
      - currency
      description: Object containing amount and currency
      title: Money
    OfferType:
      type: string
      enum:
      - PAY_IN_4
      description: Type of the offer
      title: OfferType
    AgreementEventResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AgreementEventResponseType'
          description: Type of event
        created:
          type: string
          format: date-time
          description: Timestamp when the event occurred
        amount:
          $ref: '#/components/schemas/Money'
          description: Amount associated with the event
        status:
          $ref: '#/components/schemas/AgreementEventResponseStatus'
          description: Status of the agreement at the time of the event
        merchantReference:
          type:
          - string
          - 'null'
          description: Merchant's reference associated with this event
        orderId:
          type: number
          format: double
          description: Order ID associated with this event
      description: Response type for agreement events
      title: AgreementEventResponse
    BillingAgreementResponseType:
      type: string
      enum:
      - BILLING
      description: Type of agreement
      title: BillingAgreementResponseType
    AgreementEventResponseType:
      type: string
      enum:
      - CAPTURE
      - VOID
      description: Type of event
      title: AgreementEventResponseType
    BillingAgreementApprovalResponse:
      type: object
      properties:
        token:
          type: string
          description: Token identifying this billing agreement approval request
        expires:
          type: string
          format: date-time
          description: When this approval request expires
        redirectCheckoutUrl:
          type: string
          format: uri
          description: URL where the consumer should be redirected to complete approval
      required:
      - token
      - expires
      - redirectCheckoutUrl
      description: Response from initiating a billing agreement approval process
      title: BillingAgreementApprovalResponse
    BillingAgreementApprovalRequest:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
          description: Consumer details for the billing agreement
        merchant:
          $ref: '#/components/schemas/BillingAgreementApprovalRequestMerchant'
        merchantReference:
          type: string
          description: Merchant's unique reference for this billing agreement
        agreements:
          type: array
          items:
            $ref: '#/components/schemas/AgreementApproval'
          description: Agreement type for approval (only single agreement is supported)
      required:
      - merchant
      description: Request body for initiating a billing agreement approval process
      title: BillingAgreementApprovalRequest
    BillingAgreementResponse:
      type: object
      properties:
        token:
          type: string
          description: Unique token identifying the agreement
        type:
          $ref: '#/components/schemas/BillingAgreementResponseType'
          description: Type of agreement
        status:
          $ref: '#/components/schemas/BillingAgreementResponseStatus'
          description: Current status of the agreement
        merchantReference:
          type:
          - string
          - 'null'
          description: Merchant's reference for this agreement
        created:
          type: string
          format: date-time
          description: Timestamp when the agreement was created
        cancelled:
          type: string
          format: date-time
          description: If present, indicates when the agreement was cancelled
        expires:
          type: string
          format: date-time
          description: If present, indicates when the agreement's status will become EXPIRED, preventing a client from using it to create payments
        events:
          type: array
          items:
            $ref: '#/components/schemas/AgreementEventResponse'
          description: List of events associated with this agreement
        requestId:
          type:
          - string
          - 'null'
          description: Unique identifier for the request
        consumerReference:
          type:
          - string
          - 'null'
          description: Reference identifier for the consumer
        email:
          type:
          - string
          - 'null'
          description: Masked email address of the consumer
      required:
      - token
      - type
      - status
      - created
      description: Response type for billing agreements
      title: BillingAgreementResponse
    LinkStartResponse:
      type: object
      properties:
        token:
          type: string
          description: Token identifying the billing agreement to be created
        requestId:
          type: string
          description: The unique identifier from the request
        expiresAt:
          type: string
          format: date-time
          description: When this link attempt will expire
        deliveryType:
          $ref: '#/components/schemas/LinkStartResponseDeliveryType'
          description: How the verification code was delivered to the consumer
      required:
      - token
      - requestId
      - expiresAt
      - deliveryType
      description: Response containing the billing agreement link details
      title: LinkStartResponse
    OffersResponse:
      type: object
      properties:
        consumerMaskedEmail:
          type: string
          description: Masked email address of the consumer
        consumerAmount:
          $ref: '#/components/schemas/Money'
          description: Amount in consumer's currency
        offers:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          description: List of available offers details
      description: Response containing available offers for the consumer
      title: OffersResponse
    OffersRequest:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for this request
        amount:
          $ref: '#/components/schemas/Money'
          description: The amount to check offers for
        token:
          type: string
          description: The billing agreement token
      required:
      - requestId
      - amount
      - token
      description: Request to retrieve available billing agreement offers
      title: OffersRequest
    CancelBillingAgreementRequest:
      type: object
      properties:
        token:
          type: string
          description: The billing agreement token to cancel
      required:
      - token
      description: Request to cancel a billing agreement
      title: CancelBillingAgreementRequest
    BillingAgreementResponseStatus:
      type: string
      enum:
      - ACTIVE
      - CANCELLED
      - EXPIRED
      - PENDING_RENEWAL
      - PENDING_RENEWAL_EXPIRED
      description: Current status of the agreement
      title: BillingAgreementResponseStatus
    BillingAgreementApprovalRequestMerchant:
      type: object
      properties:
        redirectConfirmUrl:
          type: string
        redirectCancelUrl:
          type: string
        popupOriginUrl:
          type: string
          description: This property is optional when a `redirectConfirmURL` is provided.
        name:
          type: string
          description: The merchant name displayed in the Afterpay approval flow.
      required:
      - redirectConfirmUrl
      - redirectCancelUrl
      title: BillingAgreementApprovalRequestMerchant
    LinkStartResponseDeliveryType:
      type: string
      enum:
      - SMS
      - EMAIL
      description: How the verification code was delivered to the consumer
      title: LinkStartResponseDeliveryType
    LinkStartRequest:
      type: object
      properties:
        alias:
          type: string
          description: Email or phone number associated with the consumer's afterpay account
        requestId:
          type: string
          description: A unique identifier for this request
      required:
      - alias
      - requestId
      description: Request to start a billing agreement link flow
      title: LinkStartRequest
    Offer:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OfferType'
          description: Type of the offer
        merchantAmount:
          $ref: '#/components/schemas/Money'
          description: Amount for the merchant
        exchangeRate:
          type: number
          format: double
          description: Exchange rate for cross-border transactions
        amountDueToday:
          $ref: '#/components/schemas/Money'
          description: Amount due for immediate payment
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentSchedule'
          description: List of scheduled payments
        crossBorder:
          type: boolean
          description: Indicates if this is a cross-border transaction
        appliedPromotion:
          $ref: '#/components/schemas/Money'
          description: Amount of promotion applied
        consumer:
          $ref: '#/components/schemas/ConsumerOffers'
          description: Consumer offer details
      description: Represents an offer with payment details
      title: Offer
    AgreementApproval:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AgreementApprovalType'
          description: Agreement Type for approval.
        merchantReference:
          type:
          - string
          - 'null'
          description: A merchant-provided reference for the agreement.
      required:
      - type
      description: Details about the agreement to be created.
      title: AgreementApproval
    AgreementApprovalType:
      type: string
      enum:
      - BILLING
      description: Agreement Type for approval.
      title: AgreementApprovalType
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
      - email
      description: The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide contact and identification details for a user.
      title: Consumer
    MoneyCurrency:
      type: string
      enum:
      - AUD
      - NZD
      - USD
      - CAD
      - GBP
      title: MoneyCurrency
    BillingAgreementAliasResponse:
      type: object
      properties:
        token:
          type: string
          description: Token representing the billing agreement alias
        expiry:
          type: string
          format: date-time
          description: Timestamp when the alias token expires
      required:
      - token
      - expiry
      description: Response containing the payment schedule token and its expiry
      title: BillingAgreementAliasResponse
    BillingAgreementAliasRequest:
      type: object
      properties:
        token:
          type: string
          description: Token of the billing agreement to create an alias for
        duration:
          type:
          - string
          - 'null'
          format: duration
          description: Duration of the billing agreement in ISO-8601 period format
      required:
      - token
      description: Request to create an alias for a billing agreement
      title: BillingAgreementAliasRequest
    PaymentSchedule:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Money'
          description: Amount for this payment installment
        dueDate:
          type: string
          format: date
          description: Due date for this installment
      required:
      - amount
      - dueDate
      description: Represents a scheduled payment installment
      title: PaymentSchedule
    ConsumerOffersNoPaymentUpfront:
      type: object
      properties:
        eligible:
          type: boolean
          description: Indicates if the consumer is eligible for no payment upfront
        eligibilityLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount eligible for no payment upfront
      required:
      - eligible
      - eligibilityLimit
      description: Information about the no payment upfront feature eligibility
      title: ConsumerOffersNoPaymentUpfront
    AgreementEventResponseStatus:
      type: string
      enum:
      - APPROVED
      - DECLINED
      description: Status of the agreement at the time of the event
      title: AgreementEventResponseStatus
    GetBillingAgreementRequest:
      type: object
      properties:
        token:
          type: string
          description: The billing agreement token to retrieve
      required:
      - token
      description: Request to retrieve a billing agreement by token
      title: GetBillingAgreementRequest
  securitySchemes:
    sec0:
      type: http
      scheme: basic