Sendcloud Integrations API

openapi: 3.1.0
info:
  title: Shipments Address Integrations API
  version: 3.0.0
  description: The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform.
  contact:
    name: Sendcloud API Support
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
  description: Sendcloud Production
tags:
- name: Integrations
paths:
  /integrations:
    get:
      summary: Retrieve a list of integrations
      operationId: sc-public-v2-orders-get-retrieve_a_list_of_integrations
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/retrieve-a-list-of-integrations
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nThe information returned includes the shop name and URL, the date, and the time of the last order fetch. The response indicates whether service point delivery is enabled for this integration, and for which carriers."
      description: Retrieve information about all the shop integrations currently connected to your Sendcloud account.
      parameters:
      - schema:
          type: string
        in: query
        name: ordering
        description: Specifies the field used to order the resulting response
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration'
              examples:
                RetrieveIntegrationList:
                  summary: Retrieve a list of integrations
                  value:
                  - id: 123
                    shop_name: 'Integration #1'
                    shop_url: https://example.com
                    system: api / amazon / magento
                    failing_since: '2019-08-24T14:15:22Z'
                    last_fetch: '2019-08-24T14:15:22Z'
                    last_updated_at: '2019-08-24T14:15:22Z'
                    service_point_enabled: true
                    service_point_carriers:
                    - ups
                    webhook_active: true
                    webhook_url: https://example.com
      tags:
      - Integrations
  /integrations/{id}:
    parameters:
    - schema:
        type: integer
      name: id
      in: path
      required: true
      description: The id of the integration
    get:
      summary: Retrieve an integration
      operationId: sc-public-v2-orders-get-retrieve_an_integration
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/retrieve-an-integration
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nThe information returned includes the shop name and URL, the date and the time of the last order fetch. The response will also indicate whether service point delivery is enabled for this integration, and for which carriers."
      description: Retrieve information about a specific integration using its `id`.
      tags:
      - Integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              examples:
                RetrieveIntegration:
                  summary: Retrieve an integration
                  value:
                    id: 123
                    shop_name: 'Integration #1'
                    shop_url: https://example.com
                    system: api / amazon / magento
                    failing_since: '2019-08-24T14:15:22Z'
                    last_fetch: '2019-08-24T14:15:22Z'
                    last_updated_at: '2019-08-24T14:15:22Z'
                    service_point_enabled: true
                    service_point_carriers:
                    - ups
                    webhook_active: true
                    webhook_url: https://example.com
        '404':
          $ref: '#/components/responses/404-Integrations'
    put:
      summary: Update an integration
      operationId: sc-public-v2-orders-put-update_an_integration
      x-mint:
        href: /api/v2/integrations/update-an-integration
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nUsing this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery and enable or disable service point delivery by setting `service_point_enabled` to `true` or `false`.\n\nUnlike the [Partially update an integration](/api/v2/integrations/partially-update-an-integration) endpoint, you must send all fields, even those you don't want to change.\n\nYou can obtain an integration `id` via the [Retrieve a list of integrations](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint."
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      description: Update settings for a specific integration using its `id`.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationUpdate'
              examples:
                UpdateIntegration:
                  summary: Update an integration
                  value:
                    shop_name: 'Integration #1'
                    shop_url: https://example.com
                    last_updated_at: '2019-08-24T14:15:22Z'
                    service_point_enabled: true
                    service_point_carriers:
                    - ups
                    webhook_active: true
                    webhook_url: https://example.com
          description: OK
        '400':
          $ref: '#/components/responses/400-Integration'
        '404':
          $ref: '#/components/responses/404-Integrations'
      tags:
      - Integrations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationUpdate'
            examples:
              UpdateIntegration:
                summary: Update an Integration
                value:
                  shop_name: 'Integration #1'
                  shop_url: https://example.com
                  service_point_enabled: true
                  service_point_carriers:
                  - ups
                  webhook_active: true
                  webhook_url: https://example.com
        description: ''
    patch:
      operationId: sc-public-v2-orders-patch-partial_update_an_integration
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/partially-update-an-integration
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nUsing this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery and enable or disable service point delivery by setting `service_point_enabled` to `true` or `false`.\n\nUnlike the [Update an integration](/api/v2/integrations/update-an-integration) endpoint, you can send only the fields you want to update.\n\nYou can obtain an integration `id` via the [Retrieve a list of integrations](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint."
      description: Partially update settings for a specific integration using its `id`.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationUpdate'
              examples:
                UpdateIntegration:
                  summary: Update an Integration
                  value:
                    shop_name: 'Integration #1'
                    shop_url: https://example.com
                    last_updated_at: '2019-08-24T14:15:22Z'
                    service_point_enabled: true
                    service_point_carriers:
                    - ups
                    webhook_active: true
                    webhook_url: https://example.com
                partial_update:
                  summary: Partial update of an Integration
                  value:
                    service_point_enabled: true
                    service_point_carriers:
                    - ups
          description: OK
        '400':
          $ref: '#/components/responses/400-Integration'
        '404':
          $ref: '#/components/responses/404-Integrations'
      tags:
      - Integrations
      summary: Partially update an integration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationUpdate'
            examples:
              UpdateIntegration:
                summary: Update an integration
                value:
                  shop_name: 'Integration #1'
                  shop_url: https://example.com
                  last_updated_at: '2019-08-24T14:15:22Z'
                  service_point_enabled: true
                  service_point_carriers:
                  - ups
                  webhook_active: true
                  webhook_url: https://example.com
              partial_update:
                summary: Partial update of an Integration
                value:
                  service_point_enabled: true
                  service_point_carriers:
                  - ups
    delete:
      summary: Delete an integration
      operationId: sc-public-v2-orders-delete-delete_an_integration
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/delete-an-integration
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      description: Delete a shop integration from the Sendcloud system.
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404-Integrations'
      tags:
      - Integrations
  /integrations/logs:
    get:
      summary: Retrieve all integration exception logs
      operationId: sc-public-v2-orders-get-retrieve_integrations_logs
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-sendcloud-paginated: true
      x-sendcloud-paginated-discriminator: results
      x-mint:
        href: /api/v2/integrations/retrieve-all-integration-exception-logs
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nIntegration exception logs might be generated, for example:\n\n- if some resource cannot be found\n- if API credentials are no longer valid\n\nEach log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop."
      description: Retrieve all integration exception logs. These logs are created when integrations have problems making API requests to shop systems.
      tags:
      - Integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    format: uri
                    description: Cursor based pagination url to go forward. By following this URL you can get a next batch of logs
                  previous:
                    type: string
                    format: uri
                    description: Cursor based pagination url to go backwards. By following this URL you can get a previous batch of logs
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationLog'
              examples:
                RetrieveIntegrationLogs:
                  summary: Retrieve a list of integration logs
                  value:
                    next: https://example.com
                    previous: https://example.com
                    results:
                    - id: 123
                      base_url: https://example.com
                      full_url: https://example.com/order-note.json
                      method: POST
                      response_code: 495
                      response:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        body: "<!doctype html>\n<html>\n <head>\n <title>SSL Certificate Error</title>\n </head>\n </html>\n"
                      request:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        payload:
                          order_note:
                            note: Success
                      created_at: '2023-03-01T02:02:00+01:00'
                      exception_type: requests.exceptions.SSLError
                      exception: An SSL error occurred
                      protected: false
                    - id: 124
                      integration_id: 123
                      user_id: 123
                      base_url: https://example.com
                      full_url: https://example.com/order-note.json
                      method: POST
                      response_code: 404
                      response: {}
                      request:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        payload: {}
                      created_at: '2023-03-01T02:02:00+01:00'
                      exception: PageNotFound
                      protected: false
  /integrations/{id}/logs:
    parameters:
    - schema:
        type: integer
      name: id
      in: path
      required: true
      description: The id of the integration to which the shipments belong
    get:
      summary: Retrieve exception logs for a specific integration
      operationId: sc-public-v2-orders-get-retrieve_integration_logs
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/retrieve-exception-logs-for-a-specific-integration
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>\n\nIntegration exception logs might be generated, for example:\n\n- if some resource cannot be found\n- if API credentials are no longer valid\n\nEach log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop."
      x-sendcloud-paginated: true
      x-sendcloud-paginated-discriminator: results
      description: Retrieve exception logs for a specific integration. These logs are created when integrations have problems making API requests to shop systems.
      tags:
      - Integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    format: uri
                    description: Cursor based pagination url to go forward. By following this URL you can get a next batch of logs
                  previous:
                    type: string
                    format: uri
                    description: Cursor based pagination url to go backwards. By following this URL you can get a previous batch of logs
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationLog'
              examples:
                RetrieveIntegrationLogs:
                  summary: Retrieve a list of integration logs
                  value:
                    next: https://example.com
                    previous: https://example.com
                    results:
                    - id: 123
                      base_url: https://example.com
                      full_url: https://example.com/order-note.json
                      method: POST
                      response_code: 495
                      response:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        body: "<!doctype html>\n<html>\n <head>\n <title>SSL Certificate Error</title>\n </head>\n </html>\n"
                      request:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        payload:
                          order_note:
                            note: Success
                      created_at: '2023-03-01T02:02:00+01:00'
                      exception_type: requests.exceptions.SSLError
                      exception: An SSL error occurred
                      protected: false
                    - id: 124
                      integration_id: 123
                      user_id: 123
                      base_url: https://example.com
                      full_url: https://example.com/order-note.json
                      method: POST
                      response_code: 404
                      response: {}
                      request:
                        headers:
                          Cache-Control: max-age=3600
                          Content-Type: text/html; charset=utf-8
                          Connection: keep-alive
                        payload: {}
                      created_at: '2023-03-01T02:02:00+01:00'
                      exception: PageNotFound
                      protected: false
        '404':
          $ref: '#/components/responses/404-Integrations'
    post:
      summary: Create integration exceptions logs
      operationId: sc-public-v2-orders-post-create_integration_logs
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/integrations/create-integration-exception-logs
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      description: Create integration exception logs, which will appear in the connection issue log screen of the user's integration.
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationLog'
              examples:
                CreateIntegrationLog:
                  summary: Create an integration log
                  value:
                    id: 123
                    integration_id: 123
                    user_id: 123
                    base_url: https://example.com
                    full_url: https://example.com/order-note.json
                    method: POST
                    response_code: 495
                    response:
                      headers:
                        Cache-Control: max-age=3600
                        Content-Type: text/html; charset=utf-8
                        Connection: keep-alive
                      body: "<!doctype html>\n<html>\n <head>\n <title>SSL Certificate Error</title>\n </head>\n </html>\n"
                    request:
                      headers:
                        Cache-Control: max-age=3600
                        Content-Type: text/html; charset=utf-8
                        Connection: keep-alive
                      payload:
                        order_note:
                          note: Success
                    created_at: '2023-03-01T02:02:00+01:00'
                    exception_type: requests.exceptions.SSLError
                    exception: An SSL error occurred
                    protected: false
          description: OK
        '400':
          $ref: '#/components/responses/400-IntegrationLog'
        '404':
          $ref: '#/components/responses/404-Integrations'
      tags:
      - Integrations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationLog'
            examples:
              CreateIntegrationLog:
                summary: Create an integration log
                value:
                  integration_id: 123
                  user_id: 123
                  base_url: https://example.com
                  full_url: https://example.com/order-note.json
                  method: POST
                  response_code: 495
                  response:
                    headers:
                      Cache-Control: max-age=3600
                      Content-Type: text/html; charset=utf-8
                      Connection: keep-alive
                    body: "<!doctype html>\n<html>\n <head>\n <title>SSL Certificate Error</title>\n </head>\n </html>\n"
                  request:
                    headers:
                      Cache-Control: max-age=3600
                      Content-Type: text/html; charset=utf-8
                      Connection: keep-alive
                    payload:
                      order_note:
                        note: Success
                  created_at: '2023-03-01T02:02:00+01:00'
                  exception_type: requests.exceptions.SSLError
                  exception: An SSL error occurred
  /shop-order-statuses:
    get:
      summary: Retrieve shop order statuses for an integration
      description: Fetch all available shop order statuses for the Prestashop v2 integration, in the default or selected language.
      x-mint:
        href: /api/v3/integrations/retrieve-shop-order-statuses-for-an-integration
        content: "<Warning>\n  Only the Prestashop V2 integration is supported.\n</Warning>\n\nNote that:\n\n- If the user hasn't picked a language, they will receive the status in the default language, `en-gb`.\n- If `en-gb` is not present, the user receives the status in the first language of the alphabetically ordered list."
      parameters:
      - $ref: '#/components/parameters/required_integration_id'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/show_deleted'
      responses:
        '200':
          description: All available shop order statuses for a given integration, in default or selected language.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-shop-order-statuses'
              examples:
                Response:
                  value:
                    data:
                    - external_id: 17-B
                      status: Delivered
                      deleted_at: null
                      translations:
                      - status: Delivered
                        language: en-gb
                      - status: Verzonden
                        language: nl-nl
                      - status: Geliefert
                        language: de-de
                    - external_id: 14-A
                      status: Cancelled
                      deleted_at: '2023-11-04T14:15:22Z'
                      translations:
                      - status: Cancelled
                        language: en-gb
                      - status: Geannuleerd
                        language: nl-nl
                      - status: Abgesagt
                        language: de-de
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                InvalidRequest:
                  value:
                    errors:
                    - status: '400'
                      code: non_field_errors
                      title: integration ID
                      detail: Integration ID is a required GET parameter
      operationId: sc-public-v3-integrations-get-shop_order_statuses
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      tags:
      - Integrations
    post:
      summary: Create or overwrite shop order statuses
      description: Insert shop-specific custom statuses into the Sendcloud system.
      x-mint:
        href: /api/v3/integrations/create-or-overwrite-shop-order-statuses
        content: "<Warning>\n  Only the Prestashop V2 integration is supported.\n</Warning>\n\nNote that:\n\n- Integrations can have their own custom shop statuses.\n- To get your order updates in time, Sendcloud needs to know what statuses are available.\n- This endpoint updates all existing statuses. That includes creating new statuses, changing existing ones, and deleting ones that no longer exist."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post-shop-order-statuses'
            examples:
              PostOrderShopStatuses:
                summary: Upserting available shop order statuses
                description: Setting all available shop order statuses with their available translations.
                value:
                  integration_id: 23452345
                  statuses:
                  - external_id: Send-4
                    translations:
                    - status: Sent
                      language: en-gb
                    - status: Verzonden
                      language: nl-nl
                  - external_id: '15'
                    translations:
                    - status: Delivered
                      language: en-gb
                    - status: Bezorgt
                      language: nl-nl
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: 'null'
              examples:
                Response:
                  value: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                WrongPayloadFormatRequested:
                  value:
                    errors:
                    - status: '400'
                      code: non_field_errors
                      title: Wrong format
                      detail: Wrong request format, expected object
      operationId: sc-public-v3-integrations-post-shop_order_statuses
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      tags:
      - Integrations
  /shop-order-statuses/mapping:
    get:
      summary: Retrieve custom status mapping for an integration
      description: 'Fetch a map of available shop order statuses and Sendcloud''s internal status category for the integration.

        '
      x-mint:
        href: /api/v3/integrations/retrieve-custom-status-mapping-for-an-integration
        content: "<Warning>\n  Only the Prestashop V2 integration is supported.\n</Warning>"
      parameters:
      - $ref: '#/components/parameters/required_integration_id'
      responses:
        '200':
          description: Custom status mapping for an integration.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/get-custom-status-mapping'
              examples:
                Response:
                  value:
                    data:
                      integration_id: 23452345
                      mapping:
                      - status_category: READY_TO_SEND
                        external_id: '11'
                        is_valid: true
                      - status_category: IN_TRANSIT
                        external_id: '11'
                        is_valid: true
                      - status_category: DELIVERED
                        external_id: null
                        is_valid: true
                      - status_category: CANCEL
                        external_id: '1'
                        is_valid: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                InvalidRequest:
                  value:
                    errors:
                    - status: '400'
                      code: non_field_errors
                      title: integration ID
                      detail: Integration ID is a required GET parameter
      operationId: sc-public-v3-integrations-get-shop_order_statuses_mapping
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      tags:
      - Integrations
    post:
      summary: Create or update custom status mapping for an integration
      description: Upsert a map of available shop order statuses and Sendcloud's internal status category for an integration
      x-mint:
        href: /api/v3/integrations/create-or-update-custom-status-mapping-for-an-integration
        content: "<Warning>\n  Only the Prestashop V2 integration is supported.\n</Warning>"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-custom-status-mapping'
            examples:
              PostOrderStatusesMapping:
          

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