xero-app-store.yaml

openapi: 3.0.0
info:
  version: "6.3.0"
  title: Xero AppStore 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"
paths:
  "/subscriptions/{subscriptionId}":
    get:
      tags:
        - AppStore
      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-20T03:13:48",
                          "endDate": "2021-07-20T03: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-20T03: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-20T03:13:48"
                                },
                                {
                                  "endDate": "2021-07-20T03:13:48",
                                  "id": "1a25bc96-141a-4e42-a0fa-55ed51844da4",
                                  "testMode": true,
                                  "price": {
                                    "amount": 0.20,
                                    "currency": "AUD",
                                    "id": "15c65048-1b48-4d9f-81c0-4e1cd3a4f49c"
                                  },
                                  "product": {
                                    "id": "e8d8ac02-01b3-47f7-8a22-99cfe9035cf7",
                                    "name": "Texts",
                                    "type": "METERED",
                                    "usageUnit": "txt"
                                  },
                                }
                              ]
                            }
                          ],
                          "startDate": "2021-07-20T03: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:
        - AppStore
      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.10, 
                "quantity": 22,
                "testMode": true,
                "recordedAt": "2022-09-13T02: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-21T13: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:
        - AppStore
      operationId: putUsageRecords
      summary: "Update and existing metered usage belonging to this subscription and subscription item"
      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.10, 
                "quantity": 22,
                "testMode": true,
                "recordedAt": "2022-09-13T02: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:
        - AppStore
      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-01T00: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-01T00:00:00"
                      }
                  ]
              }
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
          description: "When a failure occurs in the endpoint"
      security:
        - OAuth2: [marketplace.billing]
components:
  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
  parameters:
    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
    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
    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
    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
  schemas:
    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
    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
    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
    ProblemDetails:
      type: object
      properties:
        detail:
          type: string
        extensions:
          type: object
        instance:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
    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
    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
          type: string
          enum:
          - FIXED
          - PER_SEAT
          - METERED
        usageUnit:
          description: The unit of the usage product. e.g. "user", "minutes", "SMS", etc
          type: string
    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
    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
    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
    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