openapi: 3.2.0
info:
  title: LeafLink Marketplace V2 Credits API
  description: '# Introduction

    ## HTTP Request Notes

    All endpoints covered in this document are preceded by `https://{{domain}}/api/v2/` unless otherwise noted.


    Available domains


    - `app.leaflink.com` - production environment


    - `www.sandbox.leaflink.com` - sandbox environment


    - `www.leaflink-integrations.leaflink.com` - integrations sandbox environment


    [Learn more about sandbox environments](https://developer.leaflink.com/brands/api/authorization/#sandbox-environments)



    Request paths must end in a slash character (''/''). Those that do not will return a 400 (Bad Request) response.


    ## Dynamic Responses

    Some of our API endpoints support dynamic responses. These

    are responses that vary in content and/or object level payload size

    according to request path or query parameters.


    Available parameters are listed beneath endpoint definitions.

    '
  termsOfService: https://leaflink.com/terms-and-conditions/
  contact:
    email: support@leaflink.com
  version: ''
servers:
- url: https://app.leaflink.com/api/v2
security:
- Token: []
tags:
- description: The Credit model represents credits granted by a seller company to a customer for use in future purchases. Read-only.
  name: credits
paths:
  /credits/:
    parameters: []
    get:
      operationId: credits_list
      summary: List
      description: 'List all credits for companies the requester has CRM management access for.

        Requires Token or Application authentication. Staff users need CAN_MANAGE_CRM permission;

        Application auth requires CAN_READ_CRM role. Read-only (GET only).'
      parameters:
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      - name: ordering
        in: query
        description: Order results by field (prefix with '-' for descending). Supports id.
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status (active, used, cancelled). Supports multiple comma-separated values.
        required: false
        schema:
          type: string
      - name: reason
        in: query
        description: Filter by reason (leaflink_return, promo_new_customer, promo_existing_customer, etc.).
        required: false
        schema:
          type: string
      - name: brand
        in: query
        description: Filter by brand ID(s).
        required: false
        schema:
          type: string
      - name: customer
        in: query
        description: Filter by customer/CompanyCustomer ID(s).
        required: false
        schema:
          type: string
      - name: credit_date_after
        in: query
        description: Filter by credit date on or after this date (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
      - name: credit_date_before
        in: query
        description: Filter by credit date on or before this date (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
      - name: amount_min
        in: query
        description: Filter by minimum credit amount.
        required: false
        schema:
          type: number
      - name: amount_max
        in: query
        description: Filter by maximum credit amount.
        required: false
        schema:
          type: number
      - name: order
        in: query
        description: Filter by order UUID.
        required: false
        schema:
          type: string
      - name: company_slug
        in: query
        description: Filter by company slug.
        required: false
        schema:
          type: string
      - name: archived
        in: query
        description: Filter by archived status.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Credit'
      tags:
      - credits
  /credits/{id}/:
    parameters:
    - name: id
      in: path
      description: A unique integer value identifying this credit.
      required: true
      schema:
        type: integer
    get:
      operationId: credits_read
      summary: Read
      description: 'Retrieve a single credit by ID. Requires Token or Application authentication.

        Staff users need CAN_MANAGE_CRM permission; Application auth requires CAN_READ_CRM role.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credit'
      tags:
      - credits
components:
  schemas:
    Credit:
      type: object
      readOnly: true
      description: Credit granted by a seller company to a customer for use in future purchases. Read-only.
      properties:
        id:
          type: integer
          description: Unique identifier for the credit
          readOnly: true
        company:
          type: integer
          description: ID of the seller company that granted the credit
          readOnly: true
        customer:
          $ref: '#/components/schemas/LightCompanyCustomer'
        amount:
          type: object
          required:
          - amount
          - currency
          properties:
            amount:
              type: number
              description: Credit amount
            currency:
              type: string
              description: Currency code (e.g., USD)
          readOnly: true
        credit_date:
          type: string
          format: date
          description: Date the credit was granted
          readOnly: true
        status:
          type: string
          enum:
          - active
          - used
          - cancelled
          readOnly: true
        status_display:
          type: string
          description: Human-readable status
          readOnly: true
        reason:
          type: string
          enum:
          - leaflink_return
          - promo_new_customer
          - promo_existing_customer
          - return_defective
          - return_expired
          - return_packaging
          - return_order_issue
          - return_other
          - other
          readOnly: true
        reason_display:
          type: string
          description: Human-readable reason
          readOnly: true
        brand:
          type:
          - integer
          - 'null'
          description: Brand ID if credit is brand-specific
          readOnly: true
        order:
          type:
          - string
          - 'null'
          format: uuid
          description: Order UUID the credit is associated with
          readOnly: true
        order_display:
          type: string
          description: Seller's order reference (e.g., GDF - 8396)
          readOnly: true
        notes:
          type: string
          maxLength: 500
          readOnly: true
        applied_to:
          type:
          - string
          - 'null'
          format: uuid
          description: Order UUID this credit was applied to (if used)
          readOnly: true
        applied_to_display:
          type: string
          description: Seller's order reference for applied order
          readOnly: true
        read_only:
          type: boolean
          description: True if credit is used and cannot be modified
          readOnly: true
        archived:
          type: boolean
          description: Whether the credit has been soft-deleted
          readOnly: true
    LightCompanyCustomer:
      title: Customer
      description: Seller's customer record for the company on the buyer side of the order
      required:
      - id
      - delinquent
      type: object
      properties:
        id:
          title: Id
          description: id for the customer
          type: integer
        display_name:
          title: Display name
          description: Customer nickname if one exists, else the customer name
          type: string
          readOnly: true
        ext_acct_id:
          title: Accounting Service External ID
          description: ID of Customer in 3rd party accouting software
          type:
          - string
          - 'null'
          maxLength: 255
        delinquent:
          title: Delinquent
          description: Is this account marked delinquent?
          type: boolean
  securitySchemes:
    Token:
      description: 'You must authenticate your requests by including your API key in each request header as described below.


        Requests should include a header named `Authorization`, with the value `App {MY_API_KEY}`. Note the single space in the header value.


        Example: `Authorization: App MY_API_KEY`


        [Learn more about generating your key](https://developer.leaflink.com/brands/api/getting-started/)


        **Legacy API keys:** If you are not using an Application API key, your authorization header should include the string `Token` and access will be scoped to all companies under which the user exists as a companystaff.


        Example: `Authorization: Token MY_API_KEY`

        '
      in: header
      name: Authorization
      type: apiKey
x-tagGroups:
- name: Orders
  tags:
  - order-object
  - orders-received
  - order-payments
  - order-sales-reps
  - order-event-logs
  - line-item-object
  - line-items
- name: Products
  tags:
  - product-object
  - products
  - product-categories
  - product-subcategories
  - listing-states
  - product-images
  - product-lines
  - strains
- name: Batches
  tags:
  - batch-object
  - batches
  - product-batch-object
  - product-batches
  - batch-document-object
  - batch-documents
- name: Inventory Items
  tags:
  - inventory-item-object
  - inventory-items
- name: Facilities
  tags:
  - facility-object
  - facilities
- name: Customers
  tags:
  - customer-object
  - customers
  - contacts
  - activity-entries
  - customer-statuses
  - customer-tiers
  - credits
  - customer-tags
- name: Company Information
  tags:
  - companies
  - company-staff
  - licenses
  - license-types
  - brands
  - promocodes
  - reports
- name: Buyer Orders
  tags:
  - buyer-order-object
  - buyer-orders
- name: Retailer Inventory
  tags:
  - retailer-inventory