openapi: 3.2.0
info:
  contact:
    email: x-series.api@lightspeedhq.com
    name: Lightspeed Developer Relations
    url: https://developers.retail.lightspeed.app
  description: Lightspeed Retail (X-Series) API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://developers.lightspeedhq.com/terms
  title: 2026-07 Partner Billing API
  version: 2026-07
servers:
- url: https://{domain_prefix}.retail.lightspeed.app/api/2026-07
  variables:
    domain_prefix:
      default: example
      description: Domain prefix of the store to be operated on
security:
- bearerAuth: []
tags:
- description: Partner Billing operations
  name: Partner Billing
paths:
  /partner/billing/subscriptions:
    get:
      description: 'Returns list of partner''s subscriptions of the retailer


        🔒 Requires: `billing:partner_subscription:read` scope'
      operationId: PartnerSubscriptions
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/PartnerSubscriptions'
                    type:
                    - object
                    - 'null'
                required:
                - data
                type: object
          description: ''
      summary: List partner subscriptions
      tags:
      - Partner Billing
  /partner/billing/subscriptions/{subscription_id}:
    get:
      description: 'Returns a specific partner subscription of the retailer


        🔒 Requires: `billing:partner_subscription:read` scope'
      operationId: PartnerSubscription
      parameters:
      - in: path
        name: subscription_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PartnerSubscription'
                type: object
          description: ''
      summary: Get a partner subscription
      tags:
      - Partner Billing
  /partner/billing/token:
    post:
      description: 'Creates a partner subscription token (called by partner using retailer''s access token)


        🔒 Requires: `billing:partner_subscription:write` scope'
      operationId: PartnerToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerSubscriptionTokenRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PartnerSubscriptionTokenResponse'
                type: object
          description: ''
      summary: Create a partner subscription token
      tags:
      - Partner Billing
  /partner/billing/token/{partner_subscription_token}:
    get:
      description: 'Returns a subscription token data


        🔒 Requires: `billing:partner_subscription:read` scope'
      operationId: PartnerTokenGet
      parameters:
      - description: The partner subscription token
        in: path
        name: partner_subscription_token
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PartnerSubscriptionToken'
                type: object
          description: ''
      summary: Get subscription by token
      tags:
      - Partner Billing
  /partner/billing/update-subscription/token:
    post:
      description: 'Creates a partner subscription token with the intention of updating a subscription (called by partner using retailer''s access token)


        🔒 Requires: `billing:partner_subscription:write` scope'
      operationId: PartnerUpdateSubscriptionToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUpdateSubscriptionTokenRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PartnerSubscriptionTokenResponse'
                type: object
          description: ''
      summary: Create a partner update subscription token
      tags:
      - Partner Billing
components:
  schemas:
    PartnerSubscriptions:
      description: PartnerSubscriptions contains all the subscriptions of the retailer from all the partners
      items:
        $ref: '#/components/schemas/PartnerSubscription'
      type:
      - array
      - 'null'
    PartnerSubscriptionToken:
      description: PartnerSubscriptionToken repreasent a partner subscription token
      properties:
        components:
          example: '{components: [{"component_handle": "additional_registers", "component_price_point_handle": "basic", "quantity": 2}]}'
          type: string
        created_at:
          example: '2020-10-06T05:07:26Z'
          format: date-time
          type: string
        is_used:
          example: true
          type: boolean
        product_handle:
          example: lite
          type: string
        product_price_point_handle:
          example: marshmallow-lite
          type: string
        retailer_id:
          example: 0242ac12-001c-11eb-fa07-0f585c3d42ee
          type: string
        return_url:
          example: https://example.com/redirect
          type: string
        subscription_id:
          example: 1316881562803438000
          format: int64
          type: integer
        token:
          description: Token is a randomly generated string that is a required parameter for consent page
          example: 0a7e36eb05a94bf1a4d3daeff0f561f9
          maxLength: 32
          minLength: 32
          type: string
        used_at:
          example: '2020-10-06T07:00:38Z'
          format: date-time
          type: string
        vend_application_id:
          example: iYsePmZaddtZRNYQrr7g3Eg2ItSkTiFx
          type: string
      type: object
    PartnerUpdateSubscriptionTokenComponent:
      description: PartnerUpdateSubscriptionTokenComponent represents a component to be added to an updated subscription
      properties:
        component_handle:
          description: Unique reference for the component to be updated
          example: additional_registers
          type: string
        component_price_handle:
          description: Unique reference for the component price point to be updated to
          example: lite
          type: string
        quantity:
          description: How many components should be there after the update
          example: 1
          format: int64
          type: integer
      required:
      - component_handle
      - quantity
      type: object
    PartnerSubscriptionTokenRequest:
      description: PartnerSubscriptionTokenRequest represents the request's body for subscription token API
      properties:
        components:
          description: Components is a list of components to add on to the plan
          items:
            $ref: '#/components/schemas/PartnerSubscriptionTokenComponent'
          type: array
        coupon_code:
          description: CouponCode is the coupon code to be attached to the activation
          example: TEST10POFFFORLIFE
          type: string
        price_handle:
          description: ProductPricePointHandle is the product price point handle
          example: small-v1
          type: string
        product_handle:
          description: ProductHandle is the product handle
          example: small-v1
          type: string
        return_url:
          description: ReturnURL is the URL to which the user is redirected to after giving his/her consent
          example: https://www.example.com/return
          type: string
      required:
      - price_handle
      - product_handle
      - return_url
      type: object
    PartnerSubscriptionTokenComponent:
      description: PartnerSubscriptionTokenComponent represents a component to be added to a subscription
      properties:
        component_handle:
          description: Unique reference to the component to be included in the new subscription
          example: additional_registers
          type: string
        component_price_handle:
          description: Unique reference to the component price point
          example: lite
          type: string
        quantity:
          description: How many components should be added
          example: 1
          format: int64
          type: integer
      required:
      - component_handle
      - component_price_handle
      - quantity
      type: object
    PartnerSubscription:
      description: PartnerSubscription contains all the subscription under one partner application
      properties:
        application_id:
          type: string
        application_name:
          example: Partner Application
          type: string
        partner_subscription_info:
          items:
            $ref: '#/components/schemas/PartnerSubscriptionInfo'
          type: array
      type: object
    PartnerSubscriptionInfo:
      properties:
        charge_interval:
          example: 1
          format: int64
          type: integer
        charge_interval_unit:
          example: month
          type: string
        components:
          items:
            $ref: '#/components/schemas/ProductInfoComponent'
          type: array
        currency:
          example: nzd
          type: string
        id:
          example: '1348730086846538752'
          type: string
        next_assessment_at:
          example: '2021-02-11T20:34:42Z'
          type: string
        price_in_cents:
          example: '5000'
          type: string
        product_family_name:
          example: Marshmallow Production Subscription
          type: string
        product_name:
          example: Marshmallow Lite Subscription
          type: string
        product_price_point_name:
          example: marshmallow-product-price-point
          type: string
        state:
          example: canceled
          type: string
      type: object
    PartnerUpdateSubscriptionTokenRequest:
      description: PartnerUpdateSubscriptionTokenRequest represents the request's body for updating a subscription via token API
      properties:
        components:
          description: Components is a list of components to add on to the plan
          items:
            $ref: '#/components/schemas/PartnerUpdateSubscriptionTokenComponent'
          type: array
        price_handle:
          description: ProductPricePointHandle is the product price point handle, required if `product_handle` is specified
          example: small-v1
          type: string
        product_handle:
          description: ProductHandle is the product handle to update
          example: small-v1
          type: string
        return_url:
          description: ReturnURL is the URL to which the user is redirected to after giving his/her consent
          example: https://www.example.com/return
          type: string
      required:
      - return_url
      type: object
    ProductInfoComponent:
      properties:
        charge_interval_unit:
          example: month
          type: string
        component_name:
          example: Additional Register(s) Support
          type: string
        quantity:
          example: 2
          format: int64
          type: integer
        unit_price:
          example: 20
          format: double
          type: number
      title: ProductInfoComponent contain partner product component info.
      type: object
    PartnerSubscriptionTokenResponse:
      description: PartnerSubscriptionTokenResponse contains the token and its expiration time
      properties:
        expires_at:
          description: ExpiresAt is the exact time of token expiry in UTC timezone and displayed in RFC3339 format
          example: '2020-10-06T05:07:26Z'
          type: string
        expires_in:
          description: ExpiresIn is the number of seconds till the token is expired
          example: '86400'
          type: string
        token:
          description: Token is a randomly generated string that is a required parameter for consent page
          example: 0a7e36eb05a94bf1a4d3daeff0f561f9
          maxLength: 32
          minLength: 32
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      description: Bearer Token for API authentication.
      scheme: bearer
      type: http
externalDocs:
  description: List of tz database time zones
  url: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones