openapi: 3.0.3 info: title: Rokt Catalog csv refunds API version: 1.0.1 description: Integrate with Rokt Catalog servers: - url: https://api.shopcanal.com/platform description: Rokt Catalog Storefront Public API tags: - name: refunds paths: /refunds/: get: operationId: refunds_list description: ' Retrieve a paginated list of refund records associated with the authenticated store, reflecting its role in the order process. - **If called by a Storefront:** Returns refund records linked to orders originating from the Storefront. This includes refunds initiated *by* the Storefront and refunds initiated *by* connected Suppliers for those orders. - **If called by a Supplier:** Returns refund records linked to orders received by the Supplier from connected Storefronts. This includes refunds initiated *by* the Supplier and refunds initiated *by* the originating Storefronts for those orders. The response (`RefundSerializer`, paginated) includes details for each refund, such as the calculated `total_refunded_amount`, `currency`, the list of `refund_line_items` (with quantities and amounts), associated `order_id`, and timestamps. Pagination is cursor-based (`PlatformPagination`). Ordering is available on `created_at` and `updated_at`, defaulting to `-created_at`. ' parameters: - name: ordering required: false in: query description: Which field to use when ordering the results. schema: type: string - name: cursor required: false in: query description: The pagination cursor value. schema: type: string tags: - refunds security: - platformAppId: [] platformAppToken: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedRefundList' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' post: operationId: refunds_create description: "\nInitiate a refund for specific quantities of line items within a Rokt Catalog order. This endpoint handles refund requests originating from both Storefronts and Suppliers.\n\n**Request Body (`RefundCreateSerializer`):**\n\n- `order_id` (UUID, required): The Catalog ID of the order to be refunded.\n\n- `line_items` (list, required): A list of objects, each specifying:\n\n - `id` (UUID, required): The Catalog ID of the line item to refund.\n\n - `quantity` (integer, required): The quantity of this line item to refund.\n\n- `should_refund_shipping` (boolean, optional, **Storefront only**): If `true`, attempts to refund the original shipping cost associated with the Storefront order.\n\n- `extra_amount` (decimal string, optional, **restricted use**): Allows refunding an additional amount beyond line items/shipping (currently restricted to specific shops like SHEIN).\n\n**Process & Permissions:**\n\n1. **Identify Initiator:** Determines if the request comes from the Storefront or the Supplier by checking the order's relationships.\n\n2. **Lock Order:** Acquires a lock on the order record to prevent concurrent modifications.\n\n3. **Validate Quantities:** Checks if the requested `quantity` for each line item exceeds the currently refundable quantity (original quantity minus previously refunded quantity). If validation fails, returns `400 Bad Request` with `error_code: ITEMS_ALREADY_REFUNDED` and details of affected items.\n\n4. **Storefront-Initiated Refund:**\n\n - **Permission Check:** Verifies the Storefront has the required scope (`write_sk_refunds`). Returns `403 Forbidden` if missing.\n\n - **Dispatch:** Calculates refund amounts, creates the refund record for the Storefront in Catalog, and **asynchronously** triggers tasks to create corresponding refund records on the connected Supplier(s)' systems (e.g., via Shopify API).\n\n - **Error Handling:** If downstream Supplier refund creation fails, returns `400 Bad Request` with `error_code: SUPPLIER_REFUND_FAILED`.\n\n5. **Supplier-Initiated Refund:**\n\n - **Permission Check:** Implicitly requires the `write_refunds` scope.\n\n - **Create Supplier Refund:** Creates the refund record for the Supplier in Catalog.\n\n - **Dispatch to Storefront:** If the Supplier order originated from a Storefront with integration settings, **synchronously** attempts to create a corresponding refund record on the Storefront's order in Catalog.\n\n - **Error Handling:** If downstream Storefront refund creation fails, returns `400 Bad Request` with `error_code: SK_REFUND_FAILED`.\n\n6. **Extra Amount:** If `extra_amount` is provided and valid, creates an associated record (restricted use).\n\n**Response:** On success, returns `201 Created` with the details of the primary refund record created (either the Storefront's or the Supplier's) using `RefundSerializer`. The serializer might include details about failed downstream refunds in the `failed_to_create_refund_line_items` field for Storefront-initiated refunds.\n\n" tags: - refunds requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundCreate' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RefundCreate' multipart/form-data: schema: $ref: '#/components/schemas/RefundCreate' required: true security: - platformAppId: [] platformAppToken: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/Refund' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' /refunds/{id}/: get: operationId: refunds_retrieve description: ' Retrieve the full details for a specific refund record, identified by its Rokt Catalog `ID` (UUID) in the URL path. Access is restricted to refunds associated with orders linked to the authenticated store (`request.shop`). The response (`RefundSerializer`) includes the `total_refunded_amount`, `currency`, the list of `refund_line_items` (specifying the exact items, quantities, and subtotal refunded), the associated `order_id`, `note` (if any), `processed_at` timestamp, and other relevant details. If the refund `ID` is invalid or the refund is not associated with an order linked to your store, a `404 Not Found` error is returned. ' parameters: - in: path name: id schema: type: string required: true tags: - refunds security: - platformAppId: [] platformAppToken: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Refund' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' components: schemas: RefundCreate: type: object properties: order_id: type: string format: uuid line_items: type: array items: $ref: '#/components/schemas/LineItem' should_refund_shipping: type: boolean extra_amount: type: string format: decimal pattern: ^-?\d{0,8}(?:\.\d{0,4})?$ description: Only available to select retailers. required: - line_items - order_id Refund: type: object properties: id: type: string format: uuid readOnly: true order_id: type: string amount: type: object additionalProperties: {} readOnly: true note: type: string nullable: true maxLength: 1025 duties: nullable: true restock: type: boolean nullable: true processed_at: type: string format: date-time refund_line_items: type: array items: $ref: '#/components/schemas/RefundLineItem' shipping_refund_amount: type: string nullable: true maxLength: 128 failed_to_create_refund_line_items: type: string readOnly: true required: - amount - failed_to_create_refund_line_items - id - order_id - processed_at - refund_line_items PaginatedRefundList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/Refund' RefundLineItem: type: object properties: id: type: string format: uuid readOnly: true line_item: $ref: '#/components/schemas/LineItemRead' quantity: type: integer maximum: 2147483647 minimum: -2147483648 subtotal: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ nullable: true required: - id - line_item - quantity LineItemRead: type: object properties: id: type: string format: uuid variant_id: type: string format: uuid quantity: type: integer fulfillable_quantity: type: integer price: type: number format: double requires_shipping: type: boolean title: type: string sku: type: string required: - fulfillable_quantity - id - price - quantity - variant_id Error: type: object properties: message: type: string detail: {} LineItem: type: object properties: id: type: string format: uuid quantity: type: integer required: - id - quantity securitySchemes: basicAuth: type: http scheme: basic platformAppId: type: apiKey in: header name: X-CANAL-APP-ID platformAppToken: type: apiKey in: header name: X-CANAL-APP-TOKEN