openapi: 3.0.1
info:
  title: Carriyo Core API
  description: |-
    The Carriyo Core API manages shared reference data used across the Shipping, Returns, and Orders APIs: delivery types, order types, time slots, locations, webhooks, and shipment attributes.
  contact:
    name: Carriyo Support
    url: https://help.carriyo.com
    email: support@carriyo.com
  version: '1.0'
servers:
  - url: https://api.carriyo.com
  - url: https://demo-api.carriyo.com
security:
  - OAuth2-Production: []
    ApiKey: []
    TenantId: []
  - OAuth2-Demo: []
    ApiKey: []
    TenantId: []
tags:
  - name: Delivery Types
    description: |-
      A delivery type represents the type of delivery service chosen by the customer. Delivery types are defined by the merchant and typically have values such as "Same Day", "Next Day", or "International".
  - name: Locations
    description: |-
      A location is usually a store or warehouse used as a pickup or dropoff point for shipments or return requests. The merchant configures a location in Carriyo with a code, name, and address, and references it when creating shipments or returns.
  - name: Order Types
    description: |-
      An order type represents the order journey chosen by the customer. Order types are defined by the merchant and typically have values such as "Home Delivery" or "Click & Collect".
  - name: Time Slots
    description: |-
      A time slot is used to schedule collections (pickup) and deliveries (dropoff). Each time slot has a code, name, and a start and end time. Time slots can be presented as pre-configured options to the customer when creating a shipment or a return.
  - name: Webhooks
    description: |-
      A webhook lets Carriyo push real-time updates to your system. Carriyo sends notifications as JSON payloads over HTTPS, which your backend can use to trigger downstream actions. The webhook entity holds the configuration: triggers, target URL, custom headers, and so on.
  - name: Attributes
    description: |-
      A shipment attribute lets the merchant extend the shipment model with additional custom information that isn't natively supported in the Carriyo data model. As a merchant, you define your own custom attributes and reference them on shipments.
paths:
  /delivery-types:
    parameters: []
    post:
      summary: Create delivery type
      operationId: create-delivery-type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/delivery-type-request'
        required: false
      responses:
        '201':
          description: 'Delivery type created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-type-response'
        '400':
          description: >-
            Validation failed. For example: `code` exceeds 250 characters; `code` is required; or a
            delivery type with the same `code` already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a new delivery type.
      tags:
        - Delivery Types
    get:
      summary: List delivery types
      operationId: list-delivery-types
      responses:
        '200':
          description: 'Matching delivery types.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delivery-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's delivery types.
      tags:
        - Delivery Types
  /delivery-types/{delivery-type-id}:
    parameters:
      - schema:
          type: string
        name: delivery-type-id
        in: path
        required: true
    get:
      tags:
        - Delivery Types
      summary: Get delivery type
      operationId: get-delivery-type
      parameters:
        - name: delivery-type-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested delivery type.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified delivery type. If the delivery type has been deleted, the `deleted` property is set to `true` on the response.
    delete:
      summary: Delete delivery type
      operationId: delete-delivery-type
      parameters:
        - name: delivery-type-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Delivery type deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified delivery type and removes references to it from rules and other settings. This cannot be undone.
      tags:
        - Delivery Types
  /locations:
    post:
      tags:
        - Locations
      summary: Create location
      operationId: create-location
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/location-request'
        required: false
      responses:
        '201':
          description: 'Location created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a new location.
    get:
      tags:
        - Locations
      summary: List locations
      operationId: list-locations
      responses:
        '200':
          description: 'Matching locations.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's locations.
  /locations/{location-id}:
    get:
      tags:
        - Locations
      summary: Get location
      operationId: get-location
      parameters:
        - name: location-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested location.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified location. If the location has been deleted, the `deleted` property is set to `true` on the response.
    put:
      tags:
        - Locations
      summary: Update location
      operationId: update-location
      parameters:
        - name: location-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/location-request'
        required: false
      responses:
        '200':
          description: 'Location updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Updates the specified location. All fields are updated to the values supplied in the request body; fields omitted from the request are cleared.
    patch:
      tags:
        - Locations
      summary: Partially update location
      operationId: patch-location
      parameters:
        - name: location-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patch-location-request'
        required: false
      responses:
        '200':
          description: 'Location updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Partially updates the specified location. Only the fields included in the request body are changed; fields omitted are left unchanged. (The full `PUT` update, by contrast, clears omitted fields.)
    delete:
      tags:
        - Locations
      summary: Delete location
      operationId: delete-location
      parameters:
        - name: location-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Location deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified location and removes references to it from rules and other settings. This cannot be undone.
  /locations/bulk/import:
    post:
      tags:
        - Locations
      summary: Bulk import locations
      operationId: bulk-import-locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/location-bulk-import-request'
        description: |-
          One or more locations to create or update. Each row is processed independently;
          valid rows are applied even when other rows fail.
      responses:
        '200':
          description: Per-location import outcomes, in the same order as `location_requests`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/location-bulk-import-response'
        '400':
          description: Invalid request (for example, empty `location_requests` or batch over the tenant limit).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create or update multiple locations in one request. Each entry is matched by `location_code`:
        if a location with that code already exists it is updated; otherwise a new location is created.

        ### Processing

        - Rows are processed in parallel.
        - Duplicate `location_code` or `location_name` values **within the same request** are rejected.
        - Quota limits may reject additional rows when the tenant is at its location cap.

        ### Limits

        Batch size is capped by the tenant `bulk.import.limit` setting (commonly **20** locations per request).
        Split larger imports into multiple calls.

        ### Response

        Returns one entry per input row. Each entry includes:

        - `result`: `accepted` when the row was created or updated; `rejected` otherwise.
        - `reason`: detail when `result` is `rejected`.
        - `location`: the saved location when `result` is `accepted`.
        - `locationCode`: the code from the request (useful when `location` is absent).
  /order-types:
    parameters: []
    post:
      summary: Create order type
      operationId: create-order-type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/order-type-request'
        required: false
      responses:
        '201':
          description: 'Order type created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order-type-response'
        '400':
          description: >-
            Validation failed. For example: `code` exceeds 250 characters; `code` is required; or an order
            type with the same `code` already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a new order type.
      tags:
        - Order Types
    get:
      summary: List order types
      operationId: list-order-types
      responses:
        '200':
          description: 'Matching order types.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/order-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's order types, most recently created first.
      tags:
        - Order Types
  /order-types/{order-type-id}:
    parameters:
      - schema:
          type: string
        name: order-type-id
        in: path
        required: true
    get:
      summary: Get order type
      operationId: get-order-type
      parameters:
        - name: order-type-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested order type.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified order type. If the order type has been deleted, the `deleted` property is set to `true` on the response.
      tags:
        - Order Types
    delete:
      summary: Delete order type
      operationId: delete-order-type
      parameters:
        - name: order-type-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Order type deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order-type-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified order type and removes references to it from rules and other settings. This cannot be undone.
      tags:
        - Order Types
  /time-slots:
    parameters: []
    post:
      summary: Create time slot
      operationId: create-time-slot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/time-slot'
        required: false
      responses:
        '201':
          description: 'Time slot created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/time-slot'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a new time slot.
      tags:
        - Time Slots
    get:
      summary: List time slots
      operationId: list-time-slots
      responses:
        '200':
          description: 'Matching time slots.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/time-slot'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's time slots.
      tags:
        - Time Slots
  /time-slots/{time-slot-id}:
    parameters:
      - schema:
          type: string
        name: time-slot-id
        in: path
        required: true
    get:
      summary: Get time slot
      operationId: get-time-slot
      parameters:
        - name: time-slot-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested time slot.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/time-slot'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified time slot.
      tags:
        - Time Slots
    delete:
      summary: Delete time slot
      operationId: delete-time-slot
      parameters:
        - name: time-slot-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Time slot deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/time-slot'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified time slot. This cannot be undone.
      tags:
        - Time Slots
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create webhook
      operationId: create-webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-request'
        required: false
      responses:
        '201':
          description: 'Webhook created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a webhook subscription. The configuration sets the target URL, the
        `entity_type` to listen on (`Shipment`, `ReverseShipment`, or `ReturnRequest`), the
        statuses to deliver via `notify_status`, and any custom headers used to authenticate
        the delivery to your endpoint.
    get:
      tags:
        - Webhooks
      summary: List webhooks
      operationId: list-webhooks
      responses:
        '200':
          description: 'Matching webhooks.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/webhook-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's webhooks.
  /webhooks/{webhook-id}:
    get:
      tags:
        - Webhooks
      summary: Get webhook
      operationId: get-webhook
      parameters:
        - name: webhook-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested webhook.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified webhook.
    put:
      tags:
        - Webhooks
      summary: Update webhook
      operationId: update-webhook
      parameters:
        - name: webhook-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-request'
        required: false
      responses:
        '200':
          description: 'Webhook updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Updates the specified webhook. All fields are updated to the values supplied in the request body; fields omitted from the request are cleared.
    delete:
      tags:
        - Webhooks
      summary: Delete webhook
      operationId: delete-webhook
      parameters:
        - name: webhook-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Webhook deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified webhook. This cannot be undone.
  /webhooks/failed-events:
    get:
      tags:
        - Webhooks
      operationId: retrieve-failed-webhook-events
      summary: Retrieve failed webhook events
      description: |-
        Retrieve webhook events that failed within a given time range. The range can span up to
        1 day and can reach back as far as the last 30 days.


        A **failed webhook event** is one where Carriyo received a non-`200` response from your
        endpoint.


        Set `start_date` and `end_date` in ISO 8601 format (for example
        `2023-03-22T10:15:30.123Z`) to define the range.
      parameters:
        - name: webhook_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the Carriyo webhook configuration
          example: ACCOUNT_w1234-5678-abcd
        - name: start_date
          in: query
          required: true
          schema:
            type: string
          description: |
            The start date and time in ISO 8601 format with milliseconds.
            Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
          example: '2023-03-22T10:15:30.123Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
          description: |
            The end date and time in ISO 8601 format with milliseconds.
            Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
          example: '2023-03-22T10:15:30.123Z'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-failed-events-success-response'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-failed-events-error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /webhooks/retrigger-failed-events:
    post:
      tags:
        - Webhooks
      operationId: retrigger-failed-webhook-events
      summary: Retrigger failed webhook events
      description: |-
        Manually retrigger failed webhook events, for when your endpoint was unavailable or kept
        failing beyond the automatic retry limit.


        A **failed webhook event** is one where Carriyo received a non-`200` response from your
        endpoint.


        Specify a time range of up to 1 day, reaching back as far as the last 30 days. Each call
        retriggers at most 1,000 events.
      parameters:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-retrigger-failed-events-request'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-retrigger-failed-events-success-response'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-retrigger-failed-events-error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /attributes:
    post:
      tags:
        - Attributes
      summary: Create attribute
      operationId: create-attribute
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/attribute-request'
        required: false
      responses:
        '201':
          description: 'Attribute created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attribute-response'
        '400':
          description: Validation failed — e.g. `attribute_name` exceeds 50 characters or is not lowercase/underscore format; a required field is missing; or (for `ENUM` type) an `allowed_values` entry exceeds 250 characters or the values are not unique.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a new custom attribute. Once created, the attribute can be set on shipments, addresses, or products depending on `attribute_entity_type`.
    get:
      tags:
        - Attributes
      summary: List attributes
      operationId: list-attributes
      responses:
        '200':
          description: 'Matching attributes.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/attribute-response'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's custom attributes.
  /attributes/{attribute-id}:
    get:
      tags:
        - Attributes
      summary: Get attribute
      operationId: get-attribute
      parameters:
        - name: attribute-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested attribute.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attribute-response'
        '404':
          description: No attribute found for the given `attribute-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified custom attribute.
    put:
      tags:
        - Attributes
      summary: Update attribute
      operationId: update-attribute
      parameters:
        - name: attribute-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/attribute-update-request'
        required: false
      responses:
        '200':
          description: 'Attribute updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attribute-response'
        '400':
          description: Validation failed — e.g. (for `ENUM` type) an `allowed_values` entry exceeds 250 characters or the values are not unique, or a required field is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '404':
          description: No attribute found for the given `attribute-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Updates the specified custom attribute. Only `attribute_type` and `allowed_values` can be changed; other fields are fixed at creation time.
    delete:
      tags:
        - Attributes
      summary: Delete attribute
      operationId: delete-attribute
      parameters:
        - name: attribute-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Attribute deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attribute-response'
        '404':
          description: No attribute found for the given `attribute-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Deletes the specified custom attribute. Existing values on shipments / addresses / products are preserved but the attribute can no longer be set on new ones.
components:
  schemas:
    error-response:
      title: Error Response
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: Human-readable message(s) describing why the request failed.
        status:
          type: string
          description: HTTP status reason (e.g. `BAD_REQUEST`, `NOT_FOUND`).
        timestamp:
          type: string
          format: date-time
    delivery-type-request:
      title: Delivery Type Request
      required:
        - code
      type: object
      properties:
        code:
          type: string
          maxLength: 250
          description: Unique code identifying the delivery type. Maximum 250 characters.
        merchants:
          type: array
          items:
            type: string
      x-examples: {}
    delivery-type-response:
      title: Delivery Type Response
      required:
        - delivery_type_id
        - code
      type: object
      properties:
        delivery_type_id:
          type: string
        code:
          type: string
        merchants:
          type: array
          items:
            type: string
        deleted:
          type: boolean
      x-examples: {}
    patch-location-request:
      title: Patch Location Request
      type: object
      description: Body for partially updating a location. Include only the fields you want to change; omitted fields are left unchanged. No fields are required.
      properties:
        location_code:
          type: string
        location_name:
          type: string
        contact_name:
          type: string
        contact_email:
          type: string
          description: Conditionally mandatory based on Account Settings
        contact_phone:
          type: string
          description: Conditionally mandatory based on Account Settings
        alternate_phone:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
        coords:
          type: string
        address_codes:
          $ref: '#/components/schemas/address-codes'
        type:
          type: string
          enum:
            - business
            - residential
        shopify_location_id:
          type: string
        deleted:
          type: boolean
        merchants:
          type: array
          items:
            type: string
    location-request:
      title: Location Request
      required:
        - address1
        - city
        - contact_name
        - country
        - location_name
      type: object
      properties:
        location_code:
          type: string
        location_name:
          type: string
        contact_name:
          type: string
        contact_email:
          type: string
          description: Conditionally mandatory based on Account Settings
        contact_phone:
          type: string
          description: Conditionally mandatory based on Account Settings
        alternate_phone:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
        coords:
          type: string
        address_codes:
          $ref: '#/components/schemas/address-codes'
        type:
          type: string
          enum:
            - business
            - residential
        shopify_location_id:
          type: string
        deleted:
          type: boolean
        merchants:
          type: array
          items:
            type: string
      x-examples: {}
    location-response:
      title: Location Response
      required:
        - address1
        - city
        - contact_name
        - country
        - location_id
        - location_name
      type: object
      properties:
        location_id:
          type: string
        location_code:
          type: string
        location_name:
          type: string
        contact_name:
          type: string
        contact_email:
          type: string
        contact_phone:
          type: string
        alternate_phone:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
        coords:
          type: string
        address_codes:
          $ref: '#/components/schemas/address-codes'
        type:
          type: string
          enum:
            - business
            - residential
        shopify_location_id:
          type: string
        deleted:
          type: boolean
        merchants:
          type: array
          items:
            type: string
    location-bulk-import-request:
      title: Location bulk import request
      type: object
      required:
        - location_requests
      properties:
        location_requests:
          type: array
          description: Locations to import. Each item follows the same shape as `POST /locations`.
          items:
            $ref: '#/components/schemas/location-request'
    location-bulk-import-response:
      title: Location bulk import response
      type: object
      properties:
        result:
          type: string
          enum:
            - accepted
            - rejected
          description: Whether the row was applied (`accepted`) or skipped (`rejected`).
        location:
          $ref: '#/components/schemas/location-response'
        reason:
          type: string
          description: Human-readable detail when `result` is `rejected`.
        locationCode:
          type: string
          description: The `location_code` from the request for correlation when import failed.
    address-codes:
      title: Address Codes
      type: array
      items:
        $ref: '#/components/schemas/address-code'
    address-code:
      title: Address Code
      type: object
      description: |-
        Location-specific address identifier used in certain countries or systems to enhance
        delivery precision
      properties:
        type:
          type: string
          enum:
            - WHAT_3_WORDS
            - EMIRATES_MAKANI_CODE
            - KUWAIT_PACI_CODE
            - SAUDI_SHORT_CODE
          description: Type of address code
        value:
          type: string
          description: The actual value of the address code corresponding to the selected type
    order-type-request:
      title: Order Type Request
      required:
        - code
      type: object
      properties:
        code:
          type: string
          maxLength: 250
          description: Unique code identifying the order type. Maximum 250 characters.
        merchants:
          type: array
          items:
            type: string
      x-examples: {}
    time-slot:
      title: Time Slot
      type: object
      x-examples: {}
      properties:
        time_slot_id:
          type: string
          description: The ID to identify the time slot
        from:
          type: string
          pattern: ^[0-2][0-3]:[0-5][0-9]$
          example: '23:00'
          description: The start time for the time slot
        to:
          type: string
          pattern: ^[0-2][0-3]:[0-5][0-9]$
          example: '20:00'
          description: The end time for the time slot. Must be later than `from`.
      required:
        - time_slot_id
        - from
        - to
      description: ''
    order-type-response:
      title: Order Type Response
      required:
        - id
        - code
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        merchants:
          type: array
          items:
            type: string
        deleted:
          type: boolean
      x-examples: {}
    webhook-request:
      title: Webhook Request
      required:
        - config_name
        - url
      type: object
      properties:
        headers:
          type: object
          properties: {}
        merchants:
          type: array
          items:
            type: string
        pickup:
          type: object
          properties: {}
        dropoff:
          type: object
          properties: {}
        pickup_partner_location_ids:
          type: string
        dropoff_partner_location_ids:
          type: string
        custom_conditions:
          type: array
          items:
            type: object
            properties: {}
        config_name:
          type: string
        url:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
        entity_type:
          type: string
          enum:
            - Shipment
            - ReverseShipment
            - ReturnRequest
        notify_label_update:
          type: boolean
        notify_carriyo_label_update:
          type: boolean
        notify_rma_received_items:
          type: boolean
        notify_rma_returned_items:
          type: boolean
        notify_status:
          type: array
          items:
            type: string
        initial_retry_frequency:
          type: integer
        max_retry_count:
          type: integer
        internal:
          type: boolean
      x-examples: {}
    webhook-retrigger-failed-events-request:
      title: Webhook Retrigger Request By Date Range
      required:
        - webhook_id
        - start_date
        - end_date
      type: object
      properties:
        webhook_id:
          type: string
          description: ID of the Carriyo webhook configuration
          example: ACCOUNT_w1234-5678-abcd
        start_date:
          type: string
          format: date-time
          description: |
            The start date and time in ISO 8601 format with milliseconds.
            Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
          example: '2023-03-22T10:15:30.123Z'
        end_date:
          type: string
          format: date-time
          description: |
            The end date and time in ISO 8601 format with milliseconds.
            Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSZ
          example: '2023-03-22T10:15:30.123Z'
    webhook-retrigger-events-request:
      title: Webhook Retrigger Request By Entity Ids
      required:
        - entity_ids
        - trigger
      type: object
      properties:
        webhook_id:
          type: string
          description: ID of the Carriyo webhook configuration
          example: ACCOUNT_w1234-5678-abcd
        entity_ids:
          type: array
          items:
            type: string
          example: e1234-5678-abcd
        trigger:
          type: string
          description: |-
            trigger values:
            1. shipment status, e.g., `booked`, `ready_to_ship`, `delivered` etc
            2. `latest`:  if you want to trigger the last failed webhook event.
            3. `default_label_update`, `carriyo_label_update`
            4. `promised_delivery_update`
            5. `scheduled_collection_update`
            6. `scheduled_delivery_update`
          example: booked
    webhook-response:
      title: Webhook Response
      required:
        - config_name
        - url
      type: object
      properties:
        headers:
          type: object
          properties: {}
        merchants:
          type: array
          items:
            type: string
        pickup:
          type: object
          properties: {}
        dropoff:
          type: object
          properties: {}
        pickup_partner_location_ids:
          type: string
        dropoff_partner_location_ids:
          type: string
        custom_conditions:
          type: array
          items:
            type: object
            properties: {}
        config_id:
          type: string
        config_name:
          type: string
        url:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
        entity_type:
          type: string
          enum:
            - Shipment
            - ReverseShipment
            - ReturnRequest
        notify_label_update:
          type: boolean
        notify_carriyo_label_update:
          type: boolean
        notify_rma_received_items:
          type: boolean
        notify_rma_returned_items:
          type: boolean
        notify_status:
          type: array
          items:
            type: string
        initial_retry_frequency:
          type: integer
        max_retry_count:
          type: integer
        internal:
          type: boolean
        update_date:
          type: string
    webhook-failed-events-success-response:
      title: Webhook Failed Events Success Response
      type: object
      required:
        - original_failure_count
        - current_failure_count
        - failed_events
      properties:
        original_failure_count:
          type: integer
          description: |-
            Total number of events that originally failed within the specified time window or for
            the specified entities (e.g., shipments or return requests).
          example: 10
        current_failure_count:
          type: integer
          example: 1
          description: Total number of failed events that are still in the failed state.
        failed_events:
          type: array
          items:
            type: object
            properties:
              event_id:
                type: string
                example: e1234-5678-abcd
                description: Unique ID for the failed webhook event.
              entity_id:
                type: string
                example: S123456790
                description: |-
                  ID for the entity (shipment or return request) associated with the failed webhook
                  event.
              trigger:
                type: string
                example: booked
                description: Trigger event for the webhook (e.g., shipment booked or status update).
    webhook-failed-events-error-response:
      title: Webhook Failed Events Error Response
      type: object
      required:
        - error_message
      properties:
        error_message:
          type: string
          example: |-
            Missing input parameters. Please make sure you are passing webhook-id, start_date and
            end_date parameters.
    webhook-retrigger-failed-events-success-response:
      title: Webhook Re-Trigger Success Response
      type: object
      required:
        - original_failure_count
        - retriggered_count
        - retriggered_events
      properties:
        original_failure_count:
          type: integer
          description: |-
            Total number of events that originally failed within the specified time window or for
            the specified entities (e.g., shipments or return requests).
          example: 10
        retriggered_count:
          type: integer
          example: 1
          description: Total number of failed events that were retriggered to fulfill this request.
        retriggered_events:
          type: array
          items:
            type: object
            properties:
              event_id:
                type: string
                example: e1234-5678-abcd
                description: Unique ID for the failed webhook event.
              entity_id:
                type: string
                example: S123456790
                description: |-
                  ID for the entity (shipment or return request) associated with the failed webhook
                  event.
              trigger:
                type: string
                example: booked
                description: Trigger event for the webhook (e.g., shipment booked or status update).
    webhook-retrigger-failed-events-error-response:
      title: Webhook Re-Trigger Error Response
      type: object
      required:
        - error_message
      properties:
        error_message:
          type: string
          example: |-
            Missing input parameters. Please make sure you are passing webhook-id, start_date and
            end_date parameters.
    attribute-request:
      title: Attribute Request
      required:
        - attribute_name
        - attribute_type
        - attribute_entity_type
      type: object
      properties:
        custom_attribute_id:
          type: string
          description: Client-supplied identifier for the attribute (e.g. 'pickup_eligibility'). Used as the primary key for the attribute.
        attribute_name:
          type: string
          maxLength: 50
          pattern: '^[a-z]+$|(^[a-z]+)(_[a-z]+)+$'
          description: Attribute name. Maximum 50 characters; lowercase letters and underscores only (e.g. `pickup_eligibility`).
        allowed_values:
          type: array
          uniqueItems: true
          items:
            type: string
            maxLength: 250
          description: Permitted values. Required when `attribute_type` is `ENUM`; each value must be unique and at most 250 characters. Ignored for other types.
        attribute_type:
          type: string
          description: The attribute's data type.
          enum:
            - STRING
            - NUMBER
            - ENUM
            - BOOLEAN
            - MAP
        attribute_entity_type:
          type: string
          enum:
            - SHIPMENT
            - ADDRESS
            - PRODUCT
    attribute-response:
      title: Attribute Response
      required:
        - allowed_values
        - attribute_name
        - attribute_type
      type: object
      properties:
        custom_attribute_id:
          type: string
        attribute_name:
          type: string
        allowed_values:
          type: array
          items:
            type: string
        attribute_type:
          type: string
          enum:
            - STRING
            - NUMBER
            - ENUM
            - BOOLEAN
            - MAP
        attribute_entity_type:
          type: string
          enum:
            - SHIPMENT
            - ADDRESS
            - PRODUCT
        indexed:
          type: boolean
          description: Whether the attribute is indexed for search.
    attribute-update-request:
      title: Attribute update request
      required:
        - attribute_type
        - allowed_values
      type: object
      properties:
        attribute_type:
          type: string
          enum:
            - STRING
            - NUMBER
            - ENUM
            - BOOLEAN
            - MAP
          description: Updated attribute data type.
        allowed_values:
          type: array
          uniqueItems: true
          items:
            type: string
            maxLength: 250
          description: Updated list of allowed values (used when `attribute_type` is `ENUM`). Each value must be unique and at most 250 characters.
  securitySchemes:
    OAuth2-Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.carriyo.com/oauth/token
          scopes: {}
    OAuth2-Demo:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://demo-api.carriyo.com/oauth/token
          scopes: {}
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: "Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
    TenantId:
      type: apiKey
      in: header
      name: tenant-id
      description: "Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
