openapi: 3.1.0
info:
  title: Affirm Checkout API
  description: >-
    The Affirm Checkout API enables merchants to initiate and manage the Affirm
    buy now pay later checkout flow for customers at the point of purchase. It
    provides endpoints to create and store checkout sessions, read and update
    checkout objects, and resend checkout links via email or SMS. The API
    supports both redirect and direct checkout integration patterns. Once a
    customer authorizes a loan, the resulting checkout token is exchanged
    server-side to complete the transaction authorization via the Transactions
    API. Authentication uses HTTP Basic Authentication with the merchant's
    public and private API keys.
  version: '1.0'
  contact:
    name: Affirm Developer Support
    url: https://docs.affirm.com/developers/docs/development-quickstart
  termsOfService: https://www.affirm.com/legal/merchant-terms
externalDocs:
  description: Affirm Checkout API Reference
  url: https://docs.affirm.com/developers/reference/the-checkout-object
servers:
- url: https://api.affirm.com/api/v1
  description: Production Server
- url: https://sandbox.affirm.com/api/v1
  description: Sandbox Server
tags:
- name: Checkouts
  description: >-
    Operations for creating, retrieving, updating, and resending Affirm
    checkout sessions.
security:
- basicAuth: []
paths:
  /checkouts:
    post:
      operationId: storeCheckout
      summary: Affirm Store a Checkout
      description: >-
        Creates and stores a new checkout object on Affirm's servers, returning
        a checkout token that can be used to initiate the Affirm checkout UI.
        This endpoint is used in the server-side store pattern where checkout
        data is submitted from the merchant server rather than from the browser
        via affirm.js. The checkout token returned must be used to redirect or
        open the Affirm checkout experience for the customer.
      tags:
      - Checkouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              storeCheckoutRequestExample:
                summary: Default storeCheckout request
                x-microcks-default: true
                value:
                  merchant:
                    public_api_key: {}
                    user_confirmation_url: {}
                    user_cancel_url: {}
                    user_confirmation_url_action: {}
                    name: {}
                  shipping:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  billing:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  store:
                    name: {}
                    address: {}
                  items:
                  - {}
                  discounts: {}
                  metadata: {}
                  order_id: '500123'
                  currency: USD
                  financing_program: example_value
                  shipping_amount: 1
                  tax_amount: 1
                  total: 1
                  checkout_expiration: '2025-03-15T14:30:00Z'
                  expiration_time: '2025-03-15T14:30:00Z'
      responses:
        '200':
          description: Checkout created and stored successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkout_token:
                    type: string
                    description: >-
                      One-time-use token representing the stored checkout
                      session. Used to redirect the customer to the Affirm
                      checkout flow.
                  redirect_url:
                    type: string
                    format: uri
                    description: >-
                      URL to redirect the customer to for completing the
                      Affirm checkout flow.
              examples:
                storeCheckout200Example:
                  summary: Default storeCheckout 200 response
                  x-microcks-default: true
                  value:
                    checkout_token: abc123def456abc123def456abc123de
                    redirect_url: https://example.com/path
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /checkouts/direct:
    post:
      operationId: directCheckout
      summary: Affirm Direct Checkout
      description: >-
        Creates a checkout and directly authorizes the transaction in a single
        server-side call, without requiring the customer to interact with the
        Affirm checkout UI. This endpoint is used for the Direct API integration
        pattern where the merchant captures the customer's financing decision
        inline and handles the authorization flow programmatically. Returns a
        checkout token upon success.
      tags:
      - Checkouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              directCheckoutRequestExample:
                summary: Default directCheckout request
                x-microcks-default: true
                value:
                  merchant:
                    public_api_key: {}
                    user_confirmation_url: {}
                    user_cancel_url: {}
                    user_confirmation_url_action: {}
                    name: {}
                  shipping:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  billing:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  store:
                    name: {}
                    address: {}
                  items:
                  - {}
                  discounts: {}
                  metadata: {}
                  order_id: '500123'
                  currency: USD
                  financing_program: example_value
                  shipping_amount: 1
                  tax_amount: 1
                  total: 1
                  checkout_expiration: '2025-03-15T14:30:00Z'
                  expiration_time: '2025-03-15T14:30:00Z'
      responses:
        '200':
          description: Direct checkout authorized successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkout_token:
                    type: string
                    description: >-
                      Token representing the authorized checkout, to be
                      exchanged for a full transaction authorization.
              examples:
                directCheckout200Example:
                  summary: Default directCheckout 200 response
                  x-microcks-default: true
                  value:
                    checkout_token: abc123def456abc123def456abc123de
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /checkouts/{token}:
    get:
      operationId: readCheckout
      summary: Affirm Read a Checkout
      description: >-
        Retrieves the details of an existing checkout object by its token.
        Returns full checkout information including order totals, shipping and
        billing details, merchant configuration, checkout status, and metadata.
        Used to verify checkout state before or after the customer completes
        the Affirm flow.
      tags:
      - Checkouts
      parameters:
      - $ref: '#/components/parameters/CheckoutToken'
      responses:
        '200':
          description: Checkout object retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
              examples:
                readCheckout200Example:
                  summary: Default readCheckout 200 response
                  x-microcks-default: true
                  value:
                    checkout_id: '500123'
                    checkout_status: pending
                    checkout_flow_type: standard
                    currency: USD
                    total: 1
                    shipping_amount: 1
                    tax_amount: 1
                    order_id: '500123'
                    financial_program_name: Example Merchant
                    financial_program_external_name: Example Merchant
                    billing_frequency: example_value
                    api_version: example_value
                    product_type: standard
                    billing:
                      name: {}
                      address: {}
                      email: {}
                      phone_number: {}
                    shipping:
                      name: {}
                      address: {}
                      email: {}
                      phone_number: {}
                    merchant:
                      public_api_key: {}
                      user_confirmation_url: {}
                      user_cancel_url: {}
                      user_confirmation_url_action: {}
                      name: {}
                    metadata: {}
                    meta:
                      user_timezone: '2025-03-15T14:30:00Z'
                      tracking_uuid: 550e8400-e29b-41d4-a716-446655440000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updateCheckout
      summary: Affirm Update a Checkout
      description: >-
        Updates an existing checkout object with new or modified order
        information. Only fields included in the request body are updated;
        omitted fields retain their existing values. The checkout must not
        yet have been confirmed by the customer. Used to adjust order totals,
        shipping, or item details after the checkout session has been created.
      tags:
      - Checkouts
      parameters:
      - $ref: '#/components/parameters/CheckoutToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              updateCheckoutRequestExample:
                summary: Default updateCheckout request
                x-microcks-default: true
                value:
                  merchant:
                    public_api_key: {}
                    user_confirmation_url: {}
                    user_cancel_url: {}
                    user_confirmation_url_action: {}
                    name: {}
                  shipping:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  billing:
                    name: {}
                    address: {}
                    email: {}
                    phone_number: {}
                  store:
                    name: {}
                    address: {}
                  items:
                  - {}
                  discounts: {}
                  metadata: {}
                  order_id: '500123'
                  currency: USD
                  financing_program: example_value
                  shipping_amount: 1
                  tax_amount: 1
                  total: 1
                  checkout_expiration: '2025-03-15T14:30:00Z'
                  expiration_time: '2025-03-15T14:30:00Z'
      responses:
        '200':
          description: Checkout updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
              examples:
                updateCheckout200Example:
                  summary: Default updateCheckout 200 response
                  x-microcks-default: true
                  value:
                    checkout_id: '500123'
                    checkout_status: pending
                    checkout_flow_type: standard
                    currency: USD
                    total: 1
                    shipping_amount: 1
                    tax_amount: 1
                    order_id: '500123'
                    financial_program_name: Example Merchant
                    financial_program_external_name: Example Merchant
                    billing_frequency: example_value
                    api_version: example_value
                    product_type: standard
                    billing:
                      name: {}
                      address: {}
                      email: {}
                      phone_number: {}
                    shipping:
                      name: {}
                      address: {}
                      email: {}
                      phone_number: {}
                    merchant:
                      public_api_key: {}
                      user_confirmation_url: {}
                      user_cancel_url: {}
                      user_confirmation_url_action: {}
                      name: {}
                    metadata: {}
                    meta:
                      user_timezone: '2025-03-15T14:30:00Z'
                      tracking_uuid: 550e8400-e29b-41d4-a716-446655440000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /checkouts/{token}/resend:
    post:
      operationId: resendCheckout
      summary: Affirm Resend a Checkout
      description: >-
        Resends the Affirm checkout link to the customer via email or SMS.
        Used in telesales and remote checkout flows where the customer needs
        to complete the Affirm financing application on their own device after
        initiating the order with a merchant representative.
      tags:
      - Checkouts
      parameters:
      - $ref: '#/components/parameters/CheckoutToken'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to send the checkout link to.
                phone_number:
                  type: string
                  description: >-
                    Phone number to send the checkout link via SMS, in E.164
                    format.
            examples:
              resendCheckoutRequestExample:
                summary: Default resendCheckout request
                x-microcks-default: true
                value:
                  email: merchant@example.com
                  phone_number: example_value
      responses:
        '200':
          description: Checkout link resent successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates whether the resend was successful.
              examples:
                resendCheckout200Example:
                  summary: Default resendCheckout 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using the merchant's public API key as the
        username and private API key as the password, Base64-encoded as
        per RFC 7617.
  parameters:
    CheckoutToken:
      name: token
      in: path
      required: true
      description: >-
        The checkout token that represents the purchase and customer
        information for a specific checkout session.
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request. The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CheckoutRequest:
      type: object
      description: >-
        Request body for creating or updating an Affirm checkout session,
        containing all order and customer information required to initiate
        the Affirm financing flow.
      required:
      - merchant
      - items
      - currency
      - total
      properties:
        merchant:
          $ref: '#/components/schemas/MerchantObject'
        shipping:
          $ref: '#/components/schemas/ContactObject'
        billing:
          $ref: '#/components/schemas/ContactObject'
        store:
          $ref: '#/components/schemas/StoreObject'
        items:
          type: array
          description: >-
            Array of item objects representing the products being purchased
            in this checkout.
          items:
            $ref: '#/components/schemas/ItemObject'
          example:
          - example_value
        discounts:
          type: object
          description: >-
            A map of discount codes to discount objects. Each key is the
            discount code and each value contains the discount amount and
            name.
          additionalProperties:
            $ref: '#/components/schemas/DiscountObject'
          example: {}
        metadata:
          type: object
          description: >-
            Arbitrary key-value metadata for merchant tracking. Values must
            be strings.
          additionalProperties:
            type: string
          example: {}
        order_id:
          type: string
          description: >-
            The merchant's internal order identifier. Stored for future
            reference and reconciliation.
          example: '500123'
        currency:
          type: string
          description: >-
            Three-letter ISO 4217 currency code in uppercase. Supported
            values are USD, CAD, and GBP.
          enum:
          - USD
          - CAD
          - GBP
          example: USD
        financing_program:
          type: string
          description: >-
            Financing program code to apply to this checkout, if applicable.
            Determines the available loan terms presented to the customer.
          example: example_value
        shipping_amount:
          type: integer
          description: The total shipping amount in cents.
          minimum: 0
          example: 1
        tax_amount:
          type: integer
          description: The total tax amount in cents.
          minimum: 0
          example: 1
        total:
          type: integer
          description: The total amount of the checkout in cents (USD, CAD) or pence (GBP).
          minimum: 0
          example: 1
        checkout_expiration:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp specifying when the checkout session expires.
          example: '2025-03-15T14:30:00Z'
        expiration_time:
          type: string
          format: date-time
          description: >-
            Time-to-live deadline by which the customer must confirm the
            checkout.
          example: '2025-03-15T14:30:00Z'
    Checkout:
      type: object
      description: >-
        Represents an Affirm checkout session with full order details, customer
        information, and current checkout status.
      properties:
        checkout_id:
          type: string
          description: Unique identifier for this checkout session.
          example: '500123'
        checkout_status:
          type: string
          description: Current status of the checkout session.
          enum:
          - pending
          - confirmed
          - failed
          - expired
          example: pending
        checkout_flow_type:
          type: string
          description: The checkout flow type used for this session.
          example: classic
        currency:
          type: string
          description: ISO 4217 currency code for the checkout.
          example: USD
        total:
          type: integer
          description: Total checkout amount in cents.
          example: 1
        shipping_amount:
          type: integer
          description: Shipping cost in cents.
          example: 1
        tax_amount:
          type: integer
          description: Tax amount in cents.
          example: 1
        order_id:
          type: string
          description: Merchant's internal order identifier.
          example: '500123'
        financial_program_name:
          type: string
          description: Internal financing program identifier applied to this checkout.
          example: Example Merchant
        financial_program_external_name:
          type: string
          description: Customer-facing financing program name.
          example: Example Merchant
        billing_frequency:
          type: string
          description: Loan billing frequency for the financing applied.
          example: example_value
        api_version:
          type: string
          description: Version of the Affirm API used to create this checkout.
          example: example_value
        product_type:
          type: string
          nullable: true
          description: Product category associated with this checkout, if set.
          example: standard
        billing:
          $ref: '#/components/schemas/ContactObject'
        shipping:
          $ref: '#/components/schemas/ContactObject'
        merchant:
          $ref: '#/components/schemas/MerchantObject'
        metadata:
          type: object
          description: Additional checkout metadata.
          additionalProperties:
            type: string
          example: {}
        meta:
          type: object
          description: Affirm internal tracking information.
          properties:
            user_timezone:
              type: string
              description: The user's timezone at time of checkout.
            tracking_uuid:
              type: string
              description: Internal tracking UUID for this checkout session.
          example:
            user_timezone: '2025-03-15T14:30:00Z'
            tracking_uuid: 550e8400-e29b-41d4-a716-446655440000
    MerchantObject:
      type: object
      description: >-
        Merchant-specific configuration for the checkout, including callback
        URLs and the public API key.
      required:
      - user_confirmation_url
      - user_cancel_url
      properties:
        public_api_key:
          type: string
          description: >-
            The merchant's public API key. Required for checkout and store
            endpoints when submitting from a server context.
          example: abc123def456abc123def456abc123de
        user_confirmation_url:
          type: string
          format: uri
          description: >-
            The URL the customer is redirected to after successfully completing
            the Affirm checkout flow. A checkout_token is delivered to this URL
            via POST or GET depending on user_confirmation_url_action.
          example: https://example.com/path
        user_cancel_url:
          type: string
          format: uri
          description: >-
            The URL the customer is redirected to if they cancel or abandon
            the Affirm checkout flow.
          example: https://example.com/path
        user_confirmation_url_action:
          type: string
          description: >-
            Determines how the checkout_token is delivered to the
            user_confirmation_url. "POST" sends it as a form body field;
            "GET" appends it as a query parameter.
          enum:
          - POST
          - GET
          default: POST
          example: POST
        name:
          type: string
          description: The merchant's display name, shown to customers during checkout.
          example: Example Merchant
    ContactObject:
      type: object
      description: >-
        Contact information for shipping or billing, including name, address,
        email, and phone number.
      properties:
        name:
          $ref: '#/components/schemas/NameObject'
        address:
          $ref: '#/components/schemas/AddressObject'
        email:
          type: string
          format: email
          description: Email address for the contact.
          example: merchant@example.com
        phone_number:
          type: string
          description: Phone number for the contact in E.164 format.
          example: example_value
    NameObject:
      type: object
      description: A person's name split into first and last components.
      properties:
        first:
          type: string
          description: First name.
          example: example_value
        last:
          type: string
          description: Last name.
          example: example_value
        full:
          type: string
          description: Full name as a single string.
          example: example_value
    AddressObject:
      type: object
      description: A postal address.
      properties:
        line1:
          type: string
          description: Primary street address line.
          example: example_value
        line2:
          type: string
          description: Secondary address line (apartment, suite, unit, etc.).
          example: example_value
        city:
          type: string
          description: City or locality.
          example: example_value
        state:
          type: string
          description: State, province, or region code.
          example: example_value
        zipcode:
          type: string
          description: Postal or ZIP code.
          example: example_value
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: example_value
    ItemObject:
      type: object
      description: >-
        Represents a single line item in the checkout, including product
        details and pricing.
      required:
      - display_name
      - sku
      - unit_price
      - qty
      properties:
        display_name:
          type: string
          description: Customer-facing product name.
          example: Example Merchant
        sku:
          type: string
          description: Merchant's stock keeping unit identifier for the product.
          example: example_value
        unit_price:
          type: integer
          description: Unit price of the item in cents.
          minimum: 0
          example: 1
        qty:
          type: integer
          description: Quantity of this item in the order.
          minimum: 1
          example: 1
        item_image_url:
          type: string
          format: uri
          description: URL of the product image.
          example: https://example.com/path
        item_url:
          type: string
          format: uri
          description: URL of the product page on the merchant's website.
          example: https://example.com/path
        categories:
          type: array
          description: Nested array of category strings representing the product taxonomy.
          items:
            type: array
            items:
              type: string
          example:
          - - example_value
    StoreObject:
      type: object
      description: >-
        Address details for in-store transactions where the purchase is made
        at a physical merchant location.
      properties:
        name:
          type: string
          description: Store location name.
          example: Example Merchant
        address:
          $ref: '#/components/schemas/AddressObject'
    DiscountObject:
      type: object
      description: Represents a discount applied to the checkout.
      properties:
        discount_amount:
          type: integer
          description: The discount amount in cents.
          minimum: 0
          example: 1
        discount_display_name:
          type: string
          description: Customer-facing name or description of the discount.
          example: Example Merchant
    Error:
      type: object
      description: Standard error response returned by the Affirm API.
      properties:
        status_code:
          type: integer
          description: HTTP status code of the error.
          example: 1
        code:
          type: string
          description: Machine-readable error code string.
          example: example_value
        message:
          type: string
          description: Human-readable description of the error.
          example: example_value
        field:
          type: string
          description: The specific field that caused the error, if applicable.
          example: example_value