Xero App Store API

openapi: 3.2.0
info:
  version: 19.1.0
  title: Xero App Store API
  description: These endpoints are for Xero Partners to interact with the App Store Billing platform
  termsOfService: https://developer.xero.com/xero-developer-platform-terms-conditions/
  contact:
    name: Xero Platform Team
    email: api@xero.com
    url: https://developer.xero.com
  license:
    name: MIT
    url: https://github.com/XeroAPI/Xero-OpenAPI/blob/master/LICENSE
servers:
- description: Xero App Store API
  url: https://api.xero.com/appstore/2.0
tags:
- name: App Store
paths:
  /subscriptions/{subscriptionId}:
    get:
      tags:
      - App Store
      operationId: getSubscription
      summary: Retrieves a subscription for a given subscriptionId
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Success - return response of unique Subscription object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                currentPeriodEnd: 2021-07-20 03:13:48
                endDate: 2021-07-20 03:13:48
                id: 01b5a6f4-8936-4bfa-b703-830702312b87
                testMode: true
                organisationId: fdc5be44-9b3e-4ebb-a0e9-11b9737f9a28
                plans:
                - id: f617dd59-462f-46a1-9519-1765fd38b160
                  name: Small
                  status: ACTIVE
                  subscriptionItems:
                  - endDate: 2021-07-20 03:13:48
                    id: c7336bf6-8a47-4f13-9fc0-82420e6922c8
                    testMode: true
                    price:
                      amount: 50
                      currency: AUD
                      id: 31acefbe-bdb7-4329-84d6-51e9afd95327
                    product:
                      id: 56d66073-ff78-497b-a726-ca9d56fdafa3
                      name: Small
                      type: FIXED
                    quantity: 1
                    startDate: 2021-07-20 03:13:48
                  - endDate: 2021-07-20 03:13:48
                    id: 1a25bc96-141a-4e42-a0fa-55ed51844da4
                    testMode: true
                    price:
                      amount: 0.2
                      currency: AUD
                      id: 15c65048-1b48-4d9f-81c0-4e1cd3a4f49c
                    product:
                      id: e8d8ac02-01b3-47f7-8a22-99cfe9035cf7
                      name: Texts
                      type: METERED
                      usageUnit: txt
                startDate: 2021-07-20 03:13:48
                status: ACTIVE
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: When a failure occurs in the endpoint
      security:
      - OAuth2:
        - marketplace.billing
  /subscriptions/{subscriptionId}/items/{subscriptionItemId}/usage-records:
    post:
      tags:
      - App Store
      operationId: postUsageRecords
      summary: Send metered usage belonging to this subscription and subscription item
      parameters:
      - $ref: '#/components/parameters/idempotencyKey'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/subscriptionItemId'
      responses:
        '200':
          description: Success - return response of the record submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageRecord'
              example:
                usageRecordId: 2a90f7d9-4c10-4a23-9c34-b47225167a48
                subscriptionId: 391be708-878a-4741-acfb-c0bc9a165bdb
                subscriptionItemId: b22b150f-a0db-447d-9117-d922110add64
                productId: d2b133d9-95d8-4446-807a-ae7ebc7353f6
                pricePerUnit: 0.1
                quantity: 22
                testMode: true
                recordedAt: 2022-09-13 02:11:22
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: When a failure occurs in the endpoint
      security:
      - OAuth2:
        - marketplace.billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUsageRecord'
            example:
              timestamp: 2022-01-21 13:01:00
              quantity: 10
        description: Contains the quantity for the usage record to create
        required: true
  /subscriptions/{subscriptionId}/items/{subscriptionItemId}/usage-records/{usageRecordId}:
    put:
      tags:
      - App Store
      operationId: putUsageRecords
      summary: Update and existing metered usage belonging to this subscription and…
      parameters:
      - $ref: '#/components/parameters/idempotencyKey'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/subscriptionItemId'
      - $ref: '#/components/parameters/usageRecordId'
      responses:
        '200':
          description: Success - return response of the modified record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageRecord'
              example:
                usageRecordId: 2a90f7d9-4c10-4a23-9c34-b47225167a48
                subscriptionId: 391be708-878a-4741-acfb-c0bc9a165bdb
                subscriptionItemId: b22b150f-a0db-447d-9117-d922110add64
                productId: d2b133d9-95d8-4446-807a-ae7ebc7353f6
                pricePerUnit: 0.1
                quantity: 22
                testMode: true
                recordedAt: 2022-09-13 02:11:22
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: When a failure occurs in the endpoint
      security:
      - OAuth2:
        - marketplace.billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUsageRecord'
            example:
              quantity: 10
        description: Contains the quantity for the usage record to update
        required: true
  /subscriptions/{subscriptionId}/usage-records:
    get:
      tags:
      - App Store
      operationId: getUsageRecords
      summary: Gets all usage records related to the subscription
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Success - return a list of all usage record submitted against this subscription for this subscription period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageRecordsList'
              example:
                usageRecords:
                - usageRecordId: 206100d3-e18b-4c59-9372-e98e4367a73f
                  subscriptionId: 7c7684cf-bbfa-4fa8-8f44-eba8d1acdc5d
                  subscriptionItemId: 264f6fa2-65e6-48f4-8a92-57cde5499742
                  productId: b040838b-f85e-4e7c-8dba-5a8501e5d312
                  pricePerUnit: 2.0
                  quantity: 12
                  testMode: false
                  recordedAt: 2022-01-01 00:00:00
                - usageRecordId: 47d61dc9-3c99-4587-8d55-0985f47df4a6
                  subscriptionId: 7c7684cf-bbfa-4fa8-8f44-eba8d1acdc5d
                  subscriptionItemId: 264f6fa2-65e6-48f4-8a92-57cde5499742
                  productId: ec8033e8-5e3c-4795-bfb4-bfb85fa4557e
                  pricePerUnit: 5.0
                  quantity: 2
                  testMode: false
                  recordedAt: 2022-01-01 00:00:00
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: When a failure occurs in the endpoint
      security:
      - OAuth2:
        - marketplace.billing
components:
  schemas:
    Product:
      properties:
        id:
          description: The unique identifier for the product
          type: string
          format: uuid
        name:
          description: The name of the product
          type: string
        seatUnit:
          description: The unit of the per seat product. e.g. "user", "organisation", "SMS", etc
          type: string
        type:
          description: 'The pricing model of the product:

            * FIXED: Customers are charged a fixed amount for each billing period

            * PER_SEAT: Customers are charged based on the number of units they purchase

            * METERED: Customers are charged per use of this product

            * SIMPLE: Customers are charged on a fixed amount for each billing period with an optional add-on feature

            '
          type: string
          enum:
          - FIXED
          - PER_SEAT
          - METERED
          - SIMPLE
        usageUnit:
          description: The unit of the usage product. e.g. "user", "minutes", "SMS", etc
          type: string
    UsageRecordsList:
      description: Response to get usage record
      properties:
        usageRecords:
          description: A collection of usage records
          items:
            $ref: '#/components/schemas/UsageRecord'
          type: array
      required:
      - usageRecords
      type: object
    Plan:
      type: object
      properties:
        id:
          description: The unique identifier of the plan
          format: uuid
          type: string
        name:
          description: 'The name of the plan. It is used in the invoice line item

            description.

            '
          type: string
        status:
          description: 'Status of the plan. Available statuses are ACTIVE, CANCELED, and

            PENDING_ACTIVATION.

            '
          type: string
          enum:
          - ACTIVE
          - CANCELED
          - PENDING_ACTIVATION
        subscriptionItems:
          description: 'List of the subscription items belonging to the plan. It does not

            include cancelled subscription items.

            '
          items:
            $ref: '#/components/schemas/SubscriptionItem'
          type: array
      required:
      - id
      - name
      - status
      - subscriptionItems
    ProblemDetails:
      type: object
      properties:
        detail:
          type: string
        extensions:
          type: object
        instance:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
    CreateUsageRecord:
      description: Data transfer object for public create usage end point
      properties:
        quantity:
          description: The initial quantity for the usage record. Must be a whole number that is greater than or equal to 0
          format: int32
          type: integer
        timestamp:
          description: DateTime in UTC of when the the product was consumed/used
          format: date-time
          type: string
          x-is-datetime: true
      required:
      - quantity
      - timestamp
      type: object
    Subscription:
      type: object
      properties:
        currentPeriodEnd:
          description: 'End of the current period that the subscription has been invoiced for.

            '
          format: date-time
          type: string
          x-is-datetime: true
        endDate:
          description: If the subscription has been canceled, this is the date when the subscription ends. If null, the subscription is active and has not been cancelled
          format: date-time
          type: string
          x-is-datetime: true
        id:
          description: The unique identifier of the subscription
          format: uuid
          type: string
        organisationId:
          description: The Xero generated unique identifier for the organisation
          format: uuid
          type: string
        plans:
          description: List of plans for the subscription.
          type: array
          items:
            $ref: '#/components/schemas/Plan'
        startDate:
          description: Date when the subscription was first created.
          format: date-time
          type: string
          x-is-datetime: true
        status:
          description: Status of the subscription. Available statuses are ACTIVE, CANCELED, and PAST_DUE.
          type: string
          enum:
          - ACTIVE
          - CANCELED
          - PAST_DUE
        testMode:
          description: Boolean used to indicate if the subscription is in test mode
          type: boolean
      required:
      - id
      - organisationId
      - status
      - startDate
      - currentPeriodEnd
      - plans
    SubscriptionItem:
      type: object
      properties:
        endDate:
          description: Date when the subscription to this product will end
          format: date-time
          type: string
          x-is-datetime: true
        id:
          description: The unique identifier of the subscription item.
          format: uuid
          type: string
        price:
          description: The price of the product subscribed to.
          $ref: '#/components/schemas/Price'
        product:
          description: The product subscribed to.
          $ref: '#/components/schemas/Product'
        quantity:
          description: The quantity of the item. For a fixed product, it is 1. For a per-seat product, it is a positive integer. For metered products, it is always null.
          type: integer
        startDate:
          description: 'Date the subscription started, or will start. Note: this could be in

            the future for downgrades or reduced number of seats that haven''t taken effect yet.

            '
          format: date-time
          type: string
          x-is-datetime: true
        status:
          description: 'Status of the subscription item. Available statuses are ACTIVE, CANCELED, and

            PENDING_ACTIVATION.

            '
          type: string
          enum:
          - ACTIVE
          - CANCELED
          - PENDING_ACTIVATION
        testMode:
          description: If the subscription is a test subscription
          type: boolean
      required:
      - id
      - startDate
      - product
      - price
      - status
    UsageRecord:
      properties:
        quantity:
          description: The quantity recorded
          format: int32
          type: integer
        subscriptionId:
          description: The unique identifier of the Subscription.
          format: guid
          type: string
        subscriptionItemId:
          description: The unique identifier of the SubscriptionItem.
          format: guid
          type: string
        testMode:
          description: If the subscription is a test subscription
          type: boolean
        recordedAt:
          description: The time when this usage was recorded in UTC
          format: date-time
          type: string
          x-is-datetime: true
        usageRecordId:
          description: The unique identifier of the usageRecord.
          format: guid
          type: string
        pricePerUnit:
          description: The price per unit
          format: decimal
          type: number
        productId:
          description: The unique identifier of the linked Product
          format: guid
          type: string
      required:
      - usageRecordId
      - subscriptionId
      - subscriptionItemId
      - productId
      - pricePerUnit
      - quantity
      - testMode
      - recordedAt
      type: object
    Price:
      type: object
      properties:
        amount:
          description: The net (before tax) amount.
          type: number
          format: double
          x-is-money: true
        currency:
          description: The currency of the price.
          type: string
        id:
          description: The unique identifier of the price.
          format: uuid
          type: string
      required:
      - id
      - amount
      - currency
    UpdateUsageRecord:
      description: Data transfer object for public update usage end point
      properties:
        quantity:
          description: The new quantity for the usage record. Must be a whole number that is greater than or equal to 0
          format: int32
          type: integer
      required:
      - quantity
      type: object
  parameters:
    usageRecordId:
      required: true
      in: path
      name: usageRecordId
      x-snake: usage_record_id
      description: The unique identifier of the usage record
      example: 00000000-0000-0000-0000-000000000000
      x-example-java: UUID.fromString("00000000-0000-0000-0000-000000000000")
      x-example-php: '"00000000-0000-0000-0000-000000000000"'
      x-example-csharp: Guid.Parse("00000000-0000-0000-0000-000000000000");
      schema:
        type: string
        format: uuid
    subscriptionId:
      required: true
      in: path
      name: subscriptionId
      x-snake: subscription_id
      description: Unique identifier for Subscription object
      example: 00000000-0000-0000-0000-000000000000
      x-example-java: UUID.fromString("00000000-0000-0000-0000-000000000000")
      x-example-php: '"00000000-0000-0000-0000-000000000000"'
      x-example-csharp: Guid.Parse("00000000-0000-0000-0000-000000000000");
      schema:
        type: string
        format: uuid
    idempotencyKey:
      in: header
      name: Idempotency-Key
      x-snake: idempotency_key
      description: This allows you to safely retry requests without the risk of duplicate processing. 128 character max.
      example: KEY_VALUE
      schema:
        type: string
    subscriptionItemId:
      required: true
      in: path
      name: subscriptionItemId
      x-snake: subscription_item_id
      description: The unique identifier of the subscriptionItem
      example: 00000000-0000-0000-0000-000000000000
      x-example-java: UUID.fromString("00000000-0000-0000-0000-000000000000")
      x-example-php: '"00000000-0000-0000-0000-000000000000"'
      x-example-csharp: Guid.Parse("00000000-0000-0000-0000-000000000000");
      schema:
        type: string
        format: uuid
  securitySchemes:
    OAuth2:
      type: oauth2
      description: For more information
      flows:
        clientCredentials:
          tokenUrl: https://identity.xero.com/connect/token
          scopes:
            marketplace.billing: Grant read-only access to fixed assets