openapi: 3.2.0
info:
  title: Orders 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: Orders
paths:
  /v2/orders:
    post:
      operationId: create-grant
      summary: Create Order
      description: This is the first step in the on file grant purchase process. Use the token in the response to initiate the payment
      tags:
      - Orders
      parameters:
      - name: Authorization
        in: header
        description: Basic authentication
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_object             | One or more required fields were missing or invalid.                     |

            | unsupported_payment_type   | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            | unsupported_currency       | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
components:
  schemas:
    Enrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/Initiation'
          description: Who initiated the order
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: Metadata on the subscription details
      required:
      - initiation
      title: Enrichments
    OrderRequest:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: A unique identifier for the request, used for idempotency
        grantId:
          type: string
          description: ID of the grant used to create this order
        amount:
          $ref: '#/components/schemas/Money'
          description: The total amount of the order
        enrichments:
          $ref: '#/components/schemas/Enrichments'
          description: Describes additional fields beyond core payment information.
        autopay:
          type: boolean
          description: Experimental. Indicates whether autopay should be enabled for the order.
        paymentScheduleType:
          $ref: '#/components/schemas/OrderRequestPaymentScheduleType'
          description: The payment schedule type for the order.
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        shipping:
          $ref: '#/components/schemas/Contact'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        merchantReference:
          type: string
          description: The reference/order ID in the merchant's system
        shippingAmount:
          $ref: '#/components/schemas/Money'
          description: The shipping cost amount
        taxAmount:
          $ref: '#/components/schemas/Money'
          description: The tax amount
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
      required:
      - requestId
      - grantId
      - amount
      - enrichments
      title: OrderRequest
    Subscription:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionType'
        interval:
          $ref: '#/components/schemas/SubscriptionInterval'
        intervalCount:
          type: integer
      title: Subscription
    OrderRequestPaymentScheduleType:
      type: string
      enum:
      - DEFAULT
      description: The payment schedule type for the order.
      title: OrderRequestPaymentScheduleType
    ShippingCourierPriority:
      type: string
      enum:
      - STANDARD
      - EXPRESS
      title: ShippingCourierPriority
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: '- AU: Suburb

            - NZ: Town or City

            - UK: Postal Town

            - US: City

            - Canada: City'
        area2:
          type: string
          description: '- NZ: suburb

            - UK: village or local area.'
        region:
          type: string
          description: "- AU: State \n- NZ: Region\n- UK: County\n- US: State\n- CA: Province or Territory"
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format.
      required:
      - name
      - line1
      - area1
      - region
      - postcode
      - countryCode
      description: "This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. \n\nThe `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number.\n\n\n<Warning Title=\"Important Note\">\n  The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage \n</Warning>\n"
      title: Contact
    SubscriptionInterval:
      type: string
      enum:
      - DAY
      - WEEK
      - MONTH
      - YEAR
      title: SubscriptionInterval
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
      description: Discount applied to an order
      title: Discount
    CreateOrderResponse:
      type: object
      properties:
        token:
          type: string
        expires:
          type: string
          format: date-time
        paymentSchedule:
          type: array
          items:
            $ref: '#/components/schemas/PaymentSchedule'
          description: Experimental. The installment payment schedule for the order, when available. This field is optional while the feature is rolling out.
      required:
      - token
      - expires
      title: CreateOrderResponse
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
      description: 'Essential information for tracking a shipment. The `shippedAt` key represents the date and time when the item was shipped. This value follows the [ISO 8601 standard format](https://www.iso.org/iso-8601-date-and-time-format.html) for date and time representations.


        The `name` field indicates the courier service employed to handle the shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also known as Buy-Online-Pickup-Instore), please use "INSTORE_PICKUP" as the `name` field value.


        The `tracking` key represents a unique tracking number provided by the courier service to monitor the shipment''s progress. It''s a valuable tool for customers and businesses to track and trace their packages.


        The `priority` field tracks the shipping speed or service level associated with the delivery. '
      title: Shipping-Courier
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
      - name
      - quantity
      - price
      description: "This data model is used to store crucial product details. The `price.amount` field represents the unit price of the individual item. The `quantity` field shows the number of units of the item. The `name` field denotes the name of the product, while `sku` holds the Stock Keeping Unit identifier. 100 is the maximum number of item objects in the items array.\n<Warning Title=\"Important Note\">\n  It is crucial that the `price.amount` represents the unit price of the individual item.\n  **Never** populate the `price.amount` by multiplying the quantity by the unit cost. Always enter the price for a single unit to maintain data accuracy.\n</Warning>\n"
      title: Item
    SubscriptionType:
      type: string
      enum:
      - FIXED
      - VARIABLE
      title: SubscriptionType
    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
    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
    Initiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/InitiationActor'
          description: The party who initiated the order
      required:
      - actor
      title: Initiation
    ContactCountryCode:
      type: string
      enum:
      - AU
      - NZ
      - US
      - CA
      - GB
      title: ContactCountryCode
    InitiationActor:
      type: string
      enum:
      - CUSTOMER
      - MERCHANT
      description: The party who initiated the order
      title: InitiationActor
    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
  securitySchemes:
    sec0:
      type: http
      scheme: basic