Lengow Catalogues API

openapi: 3.2.0
info:
  contact:
    email: support@lengow.com
    name: Support
    url: http://help.lengow.com
  description: '# Getting started


    Welcome to Lengow API documentation for Channel Execution solutions, including NetAmplify for Ads Feed Management and NetMarkets for Marketplace Management.


    Lengow API is a REST-based API that allows you to:


    * List and retrieve the orders of your account

    * Execute actions on orders: acceptance, shipment, cancellation, and refund

    * Display the complete list of possible order actions authorized by each marketplace, at which status and with which mandatory or optional parameters

    * Retrieve invoice documents

    * Communicate with Zalando warehouse


    ## Technical Aspects


    * The API respects the `REST` fundamentals.

    * The base URL for the latest version is `api.lengow.io/v3.0` over `HTTPS`.

    * All data is sent and received as `JSON` by default.


    **Production URL:** https://api.lengow.io


    ### Specific types


    | types      | Description                            |

    |------------|----------------------------------------|

    | Country    | Depending on resources, countries are specified as two ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)) or three characters [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) |

    | Date       | All date/time values are specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ex: `2020-03-16T04:46:00+00:00`|

    | Currency   | All currencies are specified as three characters ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) |

    | Money      | decimal or string |


    # Manage orders


    | Method           | Endpoint                             | Description                                                                                                                                                                                                                               |

    |------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

    | GET, POST, PATCH | https://api.lengow.io/v3.0/orders/ | This endpoint allows you to retrieve and list your account orders (including the details of the order), mark the order with your internal order ID, perform actions on orders and check if they succeed. Each endpoint is detailed below. |


    ## List of order statuses


    From a Marketplace point of view, they all have their order statuses.

    In Lengow, we regroup and standardize all these statuses in the `lengow_status`.


    If you wish to filter based on the order status when retrieving orders, we advise you to rely on the `lengow_status` parameter.


    | Status             | Allowed action       | Description                                                                                                                            |

    |--------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------|

    | new                | None                 | Order was created but no action is available for now.                                                                                  |

    | waiting_acceptance | accept, refuse       | The merchant has to accept or refuse the order. Automatic acceptance tool available on your Lengow account.                            |

    | refused            | None                 | The order was refused by the merchant.                                                                                                 |

    | accepted           | None                 | The order has been accepted by the merchant and waiting for the marketplace authorization for shipping.                                |

    | waiting_shipment   | ship, cancel, refund | Depending on the marketplace the merchant can ship, cancel or refund the order.                                                        |

    | shipped            | refund               | The order is waiting for the final marketplace validation for closing. Depending on the marketplace the merchant can refund the order. |

    | closed             | None                 | The order is closed, no more actions are available.                                                                                    |

    | canceled           | refund               | The order was canceled. Depending on the marketplace, the order can be refunded.                                                       |

    | refunding          | None                 | The refund demand is waiting for the marketplace validation.                                                                           |

    | refunded           | None                 | Like `closed` status, the order is closed and no more action are available.                                                            |

    | partial_refunded   | None                 | Similar to `refunded`, but not all the lines have refunded status.                                                                     |

    | pickup_to_prepare  | None                 | The merchant has to prepare the pickup. Specific to eBay                                                                               |

    | to_pickup          | None                 | The order is ready for pickup. Specific to eBay                                                                                        |

    | pickup_completed   | None                 | The order has been picked up by the buyer. Specific to eBay                                                                            |

    | pickup_canceled    | None                 | The pickup has been cancelled. Specific to eBay                                                                                        |

    | to_refund          | refund               | The merchant has to refund the order.                                                                                                  |



    ## Orders Workflow


    The Order retrieval and update process usually flows like this with Lengow REST API:


    1. Order is placed on a marketplace

    2. Order is retrieved from the marketplace by Lengow every 15 minutes

    3. Merchants will retrieve orders that haven''t already been imported into their system. Refer to [get order endpoint](#tag/Orders/operation/Get%20Orders%20List) and the main filter to retrieve the order.

    4. Once those orders have been imported into their system successfully, the merchant can mark them by setting the merchant order ID. Refer to [set merchant order ID endpoint](#tag/Orders/operation/Set%20Order%20Merchant%20ID).

    5. Then Orders may be updated with 5 actions: Accept, Refuse, Ship, Cancel and Refund. Refers to [create an action on an order endpoint](#tag/Orders/operation/Order%20action).

    Acceptation may be automated by activating automatic order acceptance on your Lengow [account](https://my.lengow.io/company/orders/acceptation).

    To know which action is available by marketplace and which parameters are required for each action, refer to [get marketplace information endpoint](#tag/Marketplaces/operation/Get%20information%20on%20marketplaces).

    7. Merchant can list all the actions on the orders and verify if they have been processed by the marketplace. Refer to [List all actions on orders endpoint](#tag/Orders/operation/Order%20action)



    The diagram below provides a simplified representation of the Lengow order workflow. It does not consider the specificities of each marketplace. It would be best to analyse the statuses and possible actions for each of your marketplaces individually. [get marketplace information endpoint](#tag/Marketplaces/operation/Get%20information%20on%20marketplaces)


    ![ORDER_WORKFLOW](/static/ORDER_WORKFLOW.png)'
  license:
    name: Proprietary
    url: http://my.lengow.io
  termsOfService: http://swagger.io/terms/
  title: Lengow API - Channel Execution Catalogues API
  version: '1.0'
  x-logo:
    altText: Lengow API
    backgroundColor: '#FFFFFF'
    url: /static/lengow_brand.png
servers:
- url: https://api.lengow.io
  description: Production
host: api.lengow.io
basePath: /
schemes: https
consumes: ' application/json'
tags:
- name: Catalogues
paths:
  /v1.0/catalogues:
    get:
      DeleteProductResponse:
        description: Response model for single product deletion.
        properties:
          product_id_value:
            description: The ID of the deleted product
            title: Product Id Value
            type: string
          status:
            description: The deletion status
            title: Status
            type: string
        required:
        - product_id_value
        - status
        title: DeleteProductResponse
        type: object
      DeleteProductsResponse:
        description: Response model for deleting multiple products.
        items:
          $ref: '#/components/schemas/DeleteProductsResponseItem'
        title: DeleteProductsResponse
        type: array
      DeleteProductsResponseItem:
        description: Response item for a single product deletion.
        properties:
          product_id_value:
            title: Product Id Value
            type: string
          status:
            title: Status
            type: string
        required:
        - product_id_value
        - status
        title: DeleteProductsResponseItem
        type: object
      DuplicateRulesRequest:
        examples:
        - rule_ids:
          - 1
          - 2
          - 3
          target_catalogue_ids:
          - 200
          - 201
          user_id: 42
        properties:
          rule_ids:
            items:
              type: integer
            title: Rule Ids
            type: array
            uniqueItems: true
          target_catalogue_ids:
            items:
              type: integer
            title: Target Catalogue Ids
            type: array
            uniqueItems: true
          user_id:
            title: User Id
            type: integer
        required:
        - user_id
        - target_catalogue_ids
        - rule_ids
        title: DuplicateRulesRequest
        type: object
      GetCatalogueResponse:
        properties:
          additional_sources:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Additional Sources
          catalogue_id:
            title: Catalogue Id
            type: integer
          created_at:
            title: Created At
            type: string
          indexed_at:
            anyOf:
            - type: string
            - type: 'null'
            title: Indexed At
          name:
            title: Name
            type: string
          product_id_key:
            title: Product Id Key
            type: string
          products_count:
            title: Products Count
            type: integer
          source:
            title: Source
            type: string
          status:
            title: Status
            type: string
          updated_at:
            title: Updated At
            type: string
        required:
        - catalogue_id
        - name
        - status
        - product_id_key
        - created_at
        - updated_at
        - indexed_at
        - source
        - products_count
        title: GetCatalogueResponse
        type: object
      GetProductResponse:
        additionalProperties: true
        title: GetProductResponse
        type: object
      HTTPValidationError:
        properties:
          detail:
            items:
              $ref: '#/components/schemas/ValidationError'
            title: Detail
            type: array
        title: HTTPValidationError
        type: object
      ListAttributesResponse:
        $ref: '#/components/schemas/PaginatedResultWithNext_str_'
        title: ListAttributesResponse
      ListCataloguesResponse:
        $ref: '#/components/schemas/PaginatedResultWithNext_ListCataloguesResponseItem_-Output'
        title: ListCataloguesResponse
      ListCataloguesResponseItem-Input:
        properties:
          additional_sources:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Additional Sources
          catalogue_id:
            title: Catalogue Id
            type: integer
          channels_count:
            title: Channels Count
            type: integer
          name:
            title: Name
            type: string
          product_id_key:
            title: Product Id Key
            type: string
          role:
            title: Role
            type: string
          status:
            title: Status
            type: string
          used_by:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Used By
        required:
        - catalogue_id
        - name
        - status
        - product_id_key
        - role
        - additional_sources
        - used_by
        - channels_count
        title: ListCataloguesResponseItem
        type: object
      ListCataloguesResponseItem-Output:
        properties:
          additional_sources:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Additional Sources
          catalogue_id:
            title: Catalogue Id
            type: integer
          channels_count:
            title: Channels Count
            type: integer
          name:
            title: Name
            type: string
          product_id_key:
            title: Product Id Key
            type: string
          role:
            title: Role
            type: string
          status:
            title: Status
            type: string
          used_by:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Used By
        required:
        - catalogue_id
        - name
        - status
        - product_id_key
        - role
        - channels_count
        title: ListCataloguesResponseItem
        type: object
      ListProductsResponse:
        $ref: '#/components/schemas/PaginatedResultWithNext_ListProductsResponseItem_'
        title: ListProductsResponse
      ListProductsResponseItem:
        properties:
          attributes:
            additionalProperties: true
            title: Attributes
            type: object
          product_id_value:
            title: Product Id Value
            type: string
        required:
        - product_id_value
        - attributes
        title: ListProductsResponseItem
        type: object
      PaginatedResultWithNext_ListCataloguesResponseItem_-Input:
        properties:
          data:
            items:
              $ref: '#/components/schemas/ListCataloguesResponseItem-Input'
            title: Data
            type: array
          limit:
            title: Limit
            type: integer
          next:
            anyOf:
            - type: string
            - type: 'null'
            title: Next
          page:
            title: Page
            type: integer
          total:
            title: Total
            type: integer
        required:
        - data
        - total
        - page
        - limit
        - next
        title: PaginatedResultWithNext[ListCataloguesResponseItem]
        type: object
      PaginatedResultWithNext_ListCataloguesResponseItem_-Output:
        properties:
          data:
            items:
              $ref: '#/components/schemas/ListCataloguesResponseItem-Output'
            title: Data
            type: array
          limit:
            title: Limit
            type: integer
          next:
            anyOf:
            - type: string
            - type: 'null'
            title: Next
          page:
            title: Page
            type: integer
          total:
            title: Total
            type: integer
        required:
        - data
        - total
        - page
        - limit
        - next
        title: PaginatedResultWithNext[ListCataloguesResponseItem]
        type: object
      PaginatedResultWithNext_ListProductsResponseItem_:
        properties:
          data:
            items:
              $ref: '#/components/schemas/ListProductsResponseItem'
            title: Data
            type: array
          limit:
            title: Limit
            type: integer
          next:
            anyOf:
            - type: string
            - type: 'null'
            title: Next
          page:
            title: Page
            type: integer
          total:
            title: Total
            type: integer
        required:
        - data
        - total
        - page
        - limit
        - next
        title: PaginatedResultWithNext[ListProductsResponseItem]
        type: object
      PaginatedResultWithNext_str_:
        properties:
          data:
            items:
              type: string
            title: Data
            type: array
          limit:
            title: Limit
            type: integer
          next:
            anyOf:
            - type: string
            - type: 'null'
            title: Next
          page:
            title: Page
            type: integer
          total:
            title: Total
            type: integer
        required:
        - data
        - total
        - page
        - limit
        - next
        title: PaginatedResultWithNext[str]
        type: object
      RuleDuplicationAttributeResponse:
        properties:
          key:
            description: The identifier of the attribute in the system
            examples:
            - price
            - SRC_123456:quantity
            title: Key
            type: string
          name:
            description: The name of the attribute
            examples:
            - price
            - quantity
            title: Name
            type: string
          source:
            description: The ID of the source this attribute is attached to
            title: Source
            type: integer
        required:
        - name
        - key
        - source
        title: RuleDuplicationAttributeResponse
        type: object
      RuleDuplicationErrorResponse:
        properties:
          attribute:
            anyOf:
            - $ref: '#/components/schemas/RuleDuplicationAttributeResponse'
            - type: 'null'
            description: The attribute related to the error, if applicable
          attributes:
            anyOf:
            - items:
                $ref: '#/components/schemas/RuleDuplicationAttributeResponse'
              type: array
            - type: 'null'
            description: The list of attributes related to the error, if applicable
            title: Attributes
          error_code:
            description: The error code identifying the type of duplication error
            enum:
            - rule_duplication.self_duplication
            - rule_duplication.source_rule.not_found
            - rule_duplication.validity_period
            - rule_duplication.referenced_attributes.not_found
            - rule_duplication.target_attribute.duplicate_new_on_not_new
            - rule_duplication.target_attribute.duplicate_not_new_on_new
            - rule_duplication.target_attribute.not_found
            - rule_duplication.target_attribute.default_rule.already_exists
            - rule_duplication.target_attribute.default_rule.already_duplicated
            - rule_duplication.unknown_error
            - catalogue.not_found
            title: Error Code
            type: string
          message:
            description: A human-readable message describing the error
            title: Message
            type: string
        required:
        - error_code
        - message
        title: RuleDuplicationErrorResponse
        type: object
      RuleDuplicationOperationEntryResponse:
        properties:
          errors:
            anyOf:
            - items:
                $ref: '#/components/schemas/RuleDuplicationErrorResponse'
              type: array
            - type: 'null'
            title: Errors
          new_rule_id:
            anyOf:
            - type: integer
            - type: 'null'
            title: New Rule Id
          source_catalogue_id:
            title: Source Catalogue Id
            type: integer
          source_rule_id:
            title: Source Rule Id
            type: integer
          success:
            title: Success
            type: boolean
          target_catalogue_id:
            title: Target Catalogue Id
            type: integer
          warnings:
            anyOf:
            - items:
                $ref: '#/components/schemas/RuleDuplicationErrorResponse'
              type: array
            - type: 'null'
            title: Warnings
        required:
        - source_rule_id
        - source_catalogue_id
        - target_catalogue_id
        - success
        title: RuleDuplicationOperationEntryResponse
        type: object
      RuleDuplicationOperationResponse:
        examples:
        - created_at: '2026-05-19T09:17:20.989272+00:00'
          failure_count: 1
          operation_id: 019e3f81-3f25-716f-8ee3-b7f651ede48e
          results:
          - new_rule_id: 74
            source_catalogue_id: 1
            source_rule_id: 19
            success: true
            target_catalogue_id: 4
          - errors:
            - error_code: rule_duplication.unknown_error
              message: 'Failed to duplicate rule 1: Missing required attribute ''quantity''.'
            source_catalogue_id: 1
            source_rule_id: 1
            success: false
            target_catalogue_id: 4
          - new_rule_id: 72
            source_catalogue_id: 1
            source_rule_id: 2
            success: true
            target_catalogue_id: 4
            warnings:
            - message: The rule has a validity period that will not be duplicated.
              warning_code: rule_duplication.validity_period
          - new_rule_id: 73
            source_catalogue_id: 1
            source_rule_id: 3
            success: true
            target_catalogue_id: 4
          success_count: 3
          total_rules: 4
          user_id: 123
        properties:
          created_at:
            anyOf:
            - format: date-time
              type: string
            - type: 'null'
            title: Created At
          failure_count:
            title: Failure Count
            type: integer
          operation_id:
            title: Operation Id
            type: string
          results:
            items:
              $ref: '#/components/schemas/RuleDuplicationOperationEntryResponse'
            title: Results
            type: array
          success_count:
            title: Success Count
            type: integer
          total_rules:
            title: Total Rules
            type: integer
          user_id:
            anyOf:
            - type: integer
            - type: 'null'
            title: User Id
        required:
        - operation_id
        - total_rules
        - success_count
        - failure_count
        - results
        title: RuleDuplicationOperationResponse
        type: object
      UpdateProductRequest:
        additionalProperties:
          anyOf:
          - type: integer
          - type: number
          - type: string
          - type: boolean
          - type: 'null'
        title: UpdateProductRequest
        type: object
      UpdateProductResponse:
        title: UpdateProductResponse
      UpdateProductsRequest:
        additionalProperties:
          $ref: '#/components/schemas/UpdateProductsRequestItem'
        title: UpdateProductsRequest
        type: object
      UpdateProductsRequestItem:
        additionalProperties:
          anyOf:
          - type: integer
          - type: number
          - type: string
          - type: boolean
          - type: 'null'
        title: UpdateProductsRequestItem
        type: object
      UpdateProductsResponse:
        additionalProperties:
          $ref: '#/components/schemas/UpdateProductsResponseItem'
        title: UpdateProductsResponse
        type: object
      UpdateProductsResponseItem:
        properties:
          errors:
            anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
            title: Errors
          status:
            title: Status
            type: string
        required:
        - status
        title: UpdateProductsResponseItem
        type: object
      UpsertProductsRequest:
        items:
          additionalProperties:
            anyOf:
            - type: integer
            - type: number
            - type: string
            - type: boolean
            - type: 'null'
          type: object
        title: UpsertProductsRequest
        type: array
      UpsertProductsResponse:
        items:
          $ref: '#/components/schemas/UpsertProductsResponseItem'
        title: UpsertProductsResponse
        type: array
      UpsertProductsResponseItem:
        properties:
          errors:
            anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
            title: Errors
          product_id_value:
            anyOf:
            - type: string
            - type: 'null'
            title: Product Id Value
          status:
            title: Status
            type: string
        required:
        - product_id_value
        - status
        - errors
        title: UpsertProductsResponseItem
        type: object
      ValidationError:
        properties:
          loc:
            items:
              anyOf:
              - type: string
              - type: integer
            title: Location
            type: array
          msg:
            title: Message
            type: string
          type:
            title: Error Type
            type: string
        required:
        - loc
        - msg
        - type
        title: ValidationError
        type: object
      description: 'Retrieve the list of catalogues associated to an account.


        Entries where `role` is `additional_source` represent additional sources. Their `catalogue_id` are listed under the `additional_sources` field of the main catalogues referencing them.


        **Closed Beta – Authorised Users Only**


        This endpoint is under development and available only to approved beta participants.


        Contact [our support](mailto:help@lengow.com).'
      operationId: list_catalogues_public_catalogues_get
      parameters:
      - description: The ID of the account
        in: query
        name: account_id
        required: true
        schema:
          description: The ID of the account
          title: Account Id
          type: integer
      - description: Page number (starts at 1)
        in: query
        name: page
        required: false
        schema:
          default: 1
          description: Page number (starts at 1)
          minimum: 1
          title: Page
          type: integer
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          description: Number of items per page
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - additional_sources:
                  - 124
                  catalogue_id: 123
                  channels_count: 3
                  name: Spring Collection
                  product_id_key: sku
                  role: main_source
                  status: enabled
                - catalogue_id: 124
                  channels_count: 2
                  name: Summer Collection
                  product_id_key: product_code
                  role: additional_source
                  status: disabled
                  used_by:
                  - 123
                - catalogue_id: 125
                  channels_count: 5
                  name: Winter Collection
                  product_id_key: sku
                  role: main_source
                  status: enabled
                limit: 20
                next: /catalogues?account_id=1&page=2&limit=20
                page: 1
                total: 3
              schema:
                $ref: '#/components/schemas/ListCataloguesResponse'
          description: A list of catalogues associated with the account.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: '[BETA] List catalogues'
      tags:
      - Catalogues
  /v1.0/catalogues/{catalogue_id}:
    get:
      DeleteProductResponse:
        description: Response model for single product deletion.
        properties:
          product_id_value:
            description: The ID of the deleted product
            title: Product Id Value
            type: string
          status:
            description: The deletion status
            title: Status
            type: string
        required:
        - product_id_value
        - status
        title: DeleteProductResponse
        type: object
      DeleteProductsResponse:
        description: Response model for deleting multiple products.
        items:
          $ref: '#/components/schemas/DeleteProductsResponseItem'
        title: DeleteProductsResponse
        type: array
      DeleteProductsResponseItem:
        description: Response item for a single product deletion.
        properties:
          product_id_value:
            title: Product Id Value
            type: string
          status:
            title: Status
            type: string
        required:
        - product_id_value
        - status
        title: DeleteProductsResponseItem
        type: object
      DuplicateRulesRequest:
        examples:
        - rule_ids:
          - 1
          - 2
          - 3
          target_catalogue_ids:
          - 200
          - 201
          user_id: 42
        properties:
          rule_ids:
            items:
              type: integer
            title: Rule Ids
            type: array
            uniqueItems: true
          target_catalogue_ids:
            items:
              type: integer
            title: Target Catalogue Ids
            type: array
            uniqueItems: true
          user_id:
            title: User Id
            type: integer
        required:
        - user_id
        - target_catalogue_ids
        - rule_ids
        title: DuplicateRulesRequest
        type: object
      GetCatalogueResponse:
        properties:
          additional_sources:
            anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
            title: Additional Sources
          catalogue_id:
            title: Catalogue Id
            type: integer
          created_at:
            title: Created At
            type: string
          indexed_at:
            anyOf:
            - type: string
            - type: 'null'
            title: Indexed At
          name:
            title: Name
            type: string
          product_id_key:
            title: Product Id Key
            type: string
          products_count:
            title: Products Count
            type: integer
          source:
            title: Source
            type: string
          status:
            title: Status
            type: string
          updated_at:
            title: Updated At
            type: string
        required:
        - catalogue_id
        - name
        - status
        - product_id_key
        - created_at
        - updated_at
        - indexed_at
        - source
        - products_count
        title: GetCatalogueResponse
        type: object
      GetProductResponse:
        additionalProperties: true
        title: GetProductRespo

# --- truncated at 32 KB (226 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lengow/refs/heads/main/openapi/lengow-catalogues-api-openapi.yml