### Example Prompt: Return Timeline

Source: https://docs.loopreturns.com/mcp/getting-started

An example prompt to get the timeline for a specific return and summarize its history.

```text
Get the timeline for return #1234 and summarize what happened.
```

--------------------------------

### Getting Started

Source: https://docs.loopreturns.com/llms.txt

Instructions for connecting an MCP client to the Loop MCP Server, providing the initial steps for integration.

```APIDOC
## Getting Started

### Description
Connect an MCP client to the Loop MCP Server.

### Method
N/A (Setup guide)

### Endpoint
N/A (Setup guide)

### Details
This guide provides the necessary steps to establish a connection between your MCP client application and the Loop MCP Server. It includes prerequisites, configuration details, and initial connection procedures.

### Request Example
(Refer to specific client library or SDK documentation for connection examples)

### Response
(Successful connection confirmation)
```

--------------------------------

### Example Prompt: Active Workflows

Source: https://docs.loopreturns.com/mcp/getting-started

An example prompt to list all active workflows within the connected Loop shop.

```text
List the active workflows in my shop.
```

--------------------------------

### Example Prompt: Recent Returns

Source: https://docs.loopreturns.com/mcp/getting-started

An example prompt to retrieve the most recent returns flagged for review from the Loop shop.

```text
Show me the most recent 5 returns flagged for review.
```

--------------------------------

### Paginated Request Example

Source: https://docs.loopreturns.com/api-reference/pagination

This cURL example demonstrates how to make a paginated GET request to the Detailed Returns List endpoint, specifying a page size and date range.

```cURL
curl --request GET \
  --url 'https://api.loopreturns.com/api/{version}/warehouse/return/list?paginate=true&pageSize=50&from=2023-01-01%2000%3A00%3A00&to=2023-12-12%2000%3A00%3A00&filter=created_at&state=open' \
  --header 'X-Authorization: <api-key>'
```

--------------------------------

### Order Line Item Example

Source: https://docs.loopreturns.com/api-reference/latest/orders/upsert-order

This example demonstrates the structure of an order line item, including product details, quantity, pricing, discounts, taxes, refunds, and duties.

```json
{
  "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
  "product": {
    "id": 1073741824
  },
  "product_variant": {
    "id": 1073741824
  },
  "quantity": 500,
  "unit_price": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "unit_price_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "unit_discounts": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "unit_discounts_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "taxable": true,
  "tax_lines": {
    "title": "OH State Tax",
    "rate": 2.5,
    "price": {
      "amount": 50000,
      "currency_code": "USD"
    }
  },
  "refunds": {
    "external_id": "refund-external-id",
    "type": "line_item",
    "amount": 1000,
    "currency_code": "USD",
    "line_item": {
      "quantity": 1,
      "restock": true
    },
    "created_at": "2023-04-25T13:25:00-05:00",
    "updated_at": "2023-04-25T13:25:00-05:00"
  },
  "discounts": {
    "external_id": "refund-external-id",
    "name": "Discount Name",
    "discount_type": "amount",
    "code": "AB123",
    "reason": "This is a discount reason.",
    "rate": 1.4,
    "discount_relation": "x",
    "tax_adjustment_money": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "net_adjustment_money": {
      "amount": 50000,
      "currency_code": "USD"
    }
  },
  "duties": {
    "hs_code": "HS1234",
    "country_of_origin": "USA",
    "price": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "tax_lines": {
      "title": "OH Municipal Tax",
      "rate": 1.8,
      "price": {
        "amount": 50000,
        "currency_code": "USD"
      }
    }
  }
}
```

--------------------------------

### Create Return Note Request Example

Source: https://docs.loopreturns.com/api-reference/latest/return-actions/create-return-note

This example demonstrates the structure of a request to create a new note for a return. Ensure the 'content' field is populated with the desired note text.

```yaml
openapi: 3.1.0
info:
  title: Returns API
  version: v1
  description: API used for performing operations on returns.
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/return/{return_id}/note:
    post:
      tags:
        - Return Actions
      summary: Create Return Note
      description: |
        Post a new note to a return.

        ### Required API key scope
        - Returns
      operationId: createReturnNote
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnNoteRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreateReturnNote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidContentForNoteResponse'
      security:
        - api_key: []
components:
  schemas:
    CreateReturnNoteRequest:
      type: object
      required:
        - content
      properties:
        content:
          description: The content of the note.
          type: string
          examples:
            - This is a new note
    InvalidContentForNoteResponse:
      type: object
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - Content is required and must be less than 255 characters.
        data:
          type: object
          properties:
            content:
              type: string
    SuccessMessage:
      description: The value returned when the return has been queued for processing.
      type: string
      examples:
        - 'true'
  responses:
    CreateReturnNote:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessMessage'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    examples:
                      - '401'
                  http_code:
                    type: string
                    examples:
                      - GEN-UNAUTHORIZED
                  message:
                    type: string
                    examples:
                      - Unauthorized.
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

```

--------------------------------

### Example Items Array for Disposition

Source: https://docs.loopreturns.com/integration-guides/grading-and-disposition

This example shows how to format the request body for setting the disposition outcome of returned items. Include line_item_id and disposition_outcome.

```json
{
  "items": [
    {
      "line_item_id": 1,
      "disposition_outcome": "back_to_stock",
      "return_processor": "warehouse-operator@example.com",
      "note": "This item will be returned to stock after bagging and tagging.",
      "inspected_at": "2024-03-31 23:59:59"
    }
  ]
}
```

--------------------------------

### Set Customer API Request Example

Source: https://docs.loopreturns.com/api-reference/latest/draft-returns/set-customer

This example demonstrates how to set customer information for a draft return using the Set Customer API. It requires the draft return ID and customer details like email.

```json
{
  "customer": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

--------------------------------

### Tag Request Data Example

Source: https://docs.loopreturns.com/api-reference/latest/orders/update-order

This example shows the structure for a tag request, which includes the name of the tag. Use this to add or manage tags associated with an order.

```json
{
  "name": "vip_customer"
}
```

--------------------------------

### Analyze Cart Request Example

Source: https://docs.loopreturns.com/api-reference/latest/checkout-plus/analyze-cart

This example shows a typical request body for analyzing a WooCommerce cart. It includes platform, region, cart details like product IDs, quantities, prices, and totals.

```json
{
  "platform": "woocommerce",
  "region": "US",
  "cartId": "cart_8c2f9e7d1a4b",
  "cart": {
    "lines": [
      {
        "id": "line_001",
        "productId": "prod_67890",
        "quantity": 2,
        "unitPrice": {
          "amount": 2500,
          "currencyCode": "USD"
        },
        "totalPrice": {
          "amount": 5000,
          "currencyCode": "USD"
        },
        "originalTotalPrice": {
          "amount": 5000,
          "currencyCode": "USD"
        },
        "title": "Classic T-Shirt"
      }
    ],
    "itemCount": 2,
    "subtotalAmount": 5000,
    "totalDiscountAmount": 0,
    "totalTaxAmount": 400,
    "discountedSubtotalAmount": 5000,
    "totalAmount": 5400,
    "currencyCode": "USD"
  }
}
```

--------------------------------

### Date-Time Format Example

Source: https://docs.loopreturns.com/api-reference/latest/orders/update-order

This example illustrates the expected format for date-time values in the API, specifically for timestamps like fulfillment dates. Ensure all date-time values adhere to this ISO 8601 format.

```string
'2023-04-25T13:25:00-05:00'
```

--------------------------------

### Get Collection

Source: https://docs.loopreturns.com/integration-guides/commerce-data

Get details for a single collection.

```APIDOC
## GET /api-reference/latest/collections/get-collection

### Description
Get details for a single collection.

### Method
GET

### Endpoint
/api-reference/latest/collections/get-collection
```

--------------------------------

### Fulfillment Object Example

Source: https://docs.loopreturns.com/api-reference/latest/orders/upsert-order

This example shows the structure of a fulfillment object, including its external ID and status.

```json
{
  "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
  "status": "success",
  "fulfilled_at": ""
}
```

--------------------------------

### Detailed Returns List with Pagination

Source: https://docs.loopreturns.com/api-reference/pagination

This example demonstrates how to paginate requests for the Detailed Returns List endpoint. It shows how to set the `paginate` and `pageSize` query parameters, and how to interpret the `nextPageUrl` and `previousPageUrl` in the response.

```APIDOC
## GET /api/{version}/warehouse/return/list

### Description
Fetches a detailed list of returns with support for pagination.

### Method
GET

### Endpoint
`/api/{version}/warehouse/return/list`

### Parameters
#### Query Parameters
- **paginate** (boolean) - Optional - Set to `true` to enable pagination. Defaults to `false`.
- **pageSize** (integer) - Optional - The number of results to return per page. Defaults to `100`, maximum is `750`.
- **from** (string) - Optional - Start date for filtering results (e.g., '2023-01-01 00:00:00').
- **to** (string) - Optional - End date for filtering results (e.g., '2023-12-12 00:00:00').
- **filter** (string) - Optional - Field to filter by (e.g., 'created_at').
- **state** (string) - Optional - The state of the return to filter by (e.g., 'open').

### Request Example
```cURL
curl --request GET \
  --url 'https://api.loopreturns.com/api/{version}/warehouse/return/list?paginate=true&pageSize=50&from=2023-01-01%2000%3A00%3A00&to=2023-12-12%2000%3A00%3A00&filter=created_at&state=open' \
  --header 'X-Authorization: <api-key>'
```

### Response
#### Success Response (200)
- **returns** (array) - A list of return objects.
- **nextPageUrl** (string) - The URL to retrieve the next page of results, or null if no next page exists.
- **previousPageUrl** (string) - The URL to retrieve the previous page of results, or null if this is the first page.

#### Response Example
```json
{
  "returns": [...],
  "nextPageUrl": "https://api.loopreturns.com/api/v1/warehouse/return/list?to=2022-07-28%2000%3A00%3A00&filter=created_at&pageSize=5&cursor=eyJjcmVhdGVkX2F0IjoiMjAyMi0wNi0yNSAxNjoyNTowMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "previousPageUrl": null
}
```
```

--------------------------------

### Initialize Draft Return Request

Source: https://docs.loopreturns.com/api-reference/latest/draft-returns/select-return-method

This HTTP request demonstrates how to initialize a draft return by sending order information via POST.

```http
POST /api/v1/draft-returns
Content-Type: application/json

{

```

--------------------------------

### OpenAPI Security Scheme Example

Source: https://docs.loopreturns.com/api-reference/latest/return-actions/process-return

Example of an OpenAPI security scheme definition using an API key for authentication.

```yaml
securitySchemes:
  api_key:
    type: apiKey
    name: X-Authorization
    in: header
```

--------------------------------

### Get Return Notes OpenAPI Specification

Source: https://docs.loopreturns.com/api-reference/latest/return-actions/get-return-notes

This OpenAPI 3.1.0 specification defines the 'get /warehouse/return/{return_id}/notes' endpoint. It details the GET request for retrieving notes associated with a specific return ID, including path parameters, response schemas for success and error cases, and security schemes.

```yaml
openapi: 3.1.0
info:
  title: Returns API
  version: v1
  description: API used for performing operations on returns.
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/return/{return_id}/notes:
    get:
      tags:
        - Return Actions
      summary: Get Return Notes
      description: |
        Get notes on a specific return using the return's ID.

        ### Required API key scope
        - Returns
      operationId: getReturnNotes
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/ReturnNotes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/NoReturnNotes'
      security:
        - api_key: []
components:
  responses:
    ReturnNotes:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties:
              notes:
                type: array
                items:
                  $ref: '#/components/schemas/ReturnNote'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    examples:
                      - '401'
                  http_code:
                    type: string
                    examples:
                      - GEN-UNAUTHORIZED
                  message:
                    type: string
                    examples:
                      - Unauthorized.
    NoReturnNotes:
      description: Unprocessable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailureMessage'
  schemas:
    ReturnNote:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the return note.
        content:
          type: string
          examples:
            - This is a sample note
          description: The content of the note.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-08-15 13:19:20'
          description: >-
            The date and time at which the note was created, using the ISO 8601
            date format.
    FailureMessage:
      description: The value returned when the return processing fails.
      type: string
      examples:
        - 'false'
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

```

--------------------------------

### List Allowlist Items with Pagination

Source: https://docs.loopreturns.com/api-reference/pagination

This example demonstrates how to paginate requests for the List Allowlist Items endpoint. It shows how to set the `paginate` and `pageSize` query parameters, and how to interpret the `nextPageUrl` and `previousPageUrl` in the response.

```APIDOC
## GET /api/{version}/allowlist/list-allowlist-items

### Description
Fetches a list of items in the allowlist with support for pagination.

### Method
GET

### Endpoint
`/api/{version}/allowlist/list-allowlist-items`

### Parameters
#### Query Parameters
- **paginate** (boolean) - Optional - Set to `true` to enable pagination. Defaults to `false`.
- **pageSize** (integer) - Optional - The number of results to return per page. Defaults to `100`, maximum is `750`.

### Response
#### Success Response (200)
- **items** (array) - A list of allowlisted items.
- **nextPageUrl** (string) - The URL to retrieve the next page of results, or null if no next page exists.
- **previousPageUrl** (string) - The URL to retrieve the previous page of results, or null if this is the first page.

#### Response Example
```json
{
  "items": [...],
  "nextPageUrl": "https://api.loopreturns.com/api/v1/allowlist/list-allowlist-items?pageSize=10&cursor=...",
  "previousPageUrl": null
}
```
```

--------------------------------

### List Blocklist Items with Pagination

Source: https://docs.loopreturns.com/api-reference/pagination

This example demonstrates how to paginate requests for the List Blocklist Items endpoint. It shows how to set the `paginate` and `pageSize` query parameters, and how to interpret the `nextPageUrl` and `previousPageUrl` in the response.

```APIDOC
## GET /api/{version}/blocklist/list-blocklist-items

### Description
Fetches a list of items in the blocklist with support for pagination.

### Method
GET

### Endpoint
`/api/{version}/blocklist/list-blocklist-items`

### Parameters
#### Query Parameters
- **paginate** (boolean) - Optional - Set to `true` to enable pagination. Defaults to `false`.
- **pageSize** (integer) - Optional - The number of results to return per page. Defaults to `100`, maximum is `750`.

### Response
#### Success Response (200)
- **items** (array) - A list of blocklisted items.
- **nextPageUrl** (string) - The URL to retrieve the next page of results, or null if no next page exists.
- **previousPageUrl** (string) - The URL to retrieve the previous page of results, or null if this is the first page.

#### Response Example
```json
{
  "items": [...],
  "nextPageUrl": "https://api.loopreturns.com/api/v1/blocklist/list-blocklist-items?pageSize=10&cursor=...",
  "previousPageUrl": null
}
```
```

--------------------------------

### Get All Webhooks (OpenAPI Specification)

Source: https://docs.loopreturns.com/api-reference/latest/programmatic-webhooks/get-webhooks

This OpenAPI specification defines the GET /webhooks endpoint for retrieving all webhook subscriptions. It outlines the request, parameters, and expected JSON response structure.

```yaml
get /webhooks
openapi: 3.1.0
info:
  title: Programmatic Webhooks API
  version: v1
  description: API used for creating, retrieving, updating, and deleting webhooks.
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Programmatic Webhooks
paths:
  /webhooks:
    get:
      tags:
        - Programmatic Webhooks
      summary: Get Webhooks
      description: |
        Get all webhook subscriptions. This includes webhooks created
        programmatically and webhooks created in the Loop Admin.
      operationId: getWebhooks
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  webhooks:
                    type: array
                    description: An array of webhook subscriptions.
                    items:
                      $ref: '#/components/schemas/Webhook'
      security:
        - oauth2:
            - developer_tools
        - api_key: []
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 12345
          description: The webhook's unique identifier.
        shop_id:
          type: integer
          examples:
            - 65432
          description: The unique identifier of the shop that created the webhook.
        topic:
          $ref: '#/components/schemas/TopicEnum'
        trigger:
          $ref: '#/components/schemas/TriggerEnum'
        url:
          $ref: '#/components/schemas/WebhookUrl'
        status:
          $ref: '#/components/schemas/StatusEnum'
    TopicEnum:
      type: string
      description: The webhook's topic.
      enum:
        - return
        - label
        - restock
        - label.request
        - giftcard
        - happy.returns.shipment
      examples:
        - return
    TriggerEnum:
      type: string
      description: The condition which triggers the webhook.
      enum:
        - return.created
        - return.updated
        - return.closed
        - label.created
        - label.updated
        - restock.requested
        - label.request.issued
        - label.request.cancelled
        - giftcard.requested
        - shipment.processed
      examples:
        - return.created
    WebhookUrl:
      type: string
      examples:
        - https://example.com/webhook
      description: The webhook's URL.
    StatusEnum:
      type: string
      description: The webhook's status.
      enum:
        - active
        - inactive
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.loopreturns.com/authorize
          tokenUrl: https://oauth.loopreturns.com/oauth/token
          scopes:
            developer_tools: Access to developer tools including webhooks
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

```

--------------------------------

### Create Product

Source: https://docs.loopreturns.com/api-reference/latest/products/create-product

This endpoint allows you to create a new product. It requires product details such as name, SKU, and pricing information. Ensure you have the necessary API key with 'Product (write)' scope for authentication.

```APIDOC
## POST /products

### Description
Creates a new product in the system.

### Method
POST

### Endpoint
/products

### Request Body
- **name** (string) - Required - The name of the product.
- **sku** (string) - Required - The Stock Keeping Unit for the product.
- **price** (object) - Required - Pricing information for the product.
  - **amount** (number) - Required - The price amount.
  - **currency_code** (string) - Required - The currency code (e.g., USD, EUR).
- **product_options** (array) - Optional - An array of product options.
  - **position** (integer) - Required - The position of the option.
  - **values** (array) - Required - The possible values for the option.
    - **items** (string) - The value of the option.
  - **name** (string) - Required - The name of the option.

### Request Example
```json
{
  "name": "Example T-Shirt",
  "sku": "TSHIRT-RED-L",
  "price": {
    "amount": 29.99,
    "currency_code": "USD"
  },
  "product_options": [
    {
      "position": 1,
      "values": ["Red", "Blue"],
      "name": "Color"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the created product.
- **external_id** (string) - The external identifier of the product.
- **name** (string) - The name of the product.

#### Response Example
```json
{
  "id": 12345,
  "external_id": "prod_abc123",
  "name": "Example T-Shirt"
}
```

### Error Handling
#### Bad Request (400)
- **error** (object) - Contains error details.
  - **code** (string) - Error code.
  - **http_code** (string) - HTTP status code.
  - **message** (string) - Error message.

#### Unauthorized (401)
- **error** (object) - Contains error details.
  - **code** (string) - Error code.
  - **http_code** (string) - HTTP status code.
  - **message** (string) - Error message.

### Headers
- **X-Authorization** (string) - Required - API Key with 'Product (write)' scope.
```

--------------------------------

### OpenAPI Specification for Get All Destinations

Source: https://docs.loopreturns.com/api-reference/latest/destinations/get-all-destinations

This OpenAPI 3.1.0 specification defines the GET /destinations endpoint for retrieving all destinations. It includes details on request parameters, responses, and security schemes.

```yaml
openapi: 3.1.0
info:
  title: Destinations API
  description: Title
  version: v1
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Destinations
paths:
  /destinations:
    get:
      tags:
        - Destinations
      summary: Get All Destinations
      description: |
        Retrieve all destinations.

        ### Required API key scope
        - Destinations (Read)
      operationId: getAllDestinations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  destinations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Destination'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
      security:
        - api_key: []
components:
  schemas:
    Destination:
      type: object
      description: >-
        A physical location such as a warehouse or donation center to which
        returns are shipped.
      properties:
        id:
          type: integer
          example: 1
          description: The destination's unique identifier.
        type:
          type: string
          enum:
            - warehouse
            - donate
          example: warehouse
          description: The type of location represented by the destination.
        name:
          type: string
          example: Example Destination
          description: The destination's name.
        enabled:
          type: boolean
          example: true
          description: Whether the destination is enabled as a return destination.
        provider_location_id:
          type:
            - integer
            - "null"
          example: 42424242
          description: >
            The numeric location identifier from the commerce platform (for
            example Shopify) when a

            location is linked to this destination in Loop. `null` when no
            location is linked. The

            linked location's `source` field indicates which provider the ID
            belongs to.
        address:
          $ref: '#/components/schemas/Address'
    UnauthorizedResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '401'
            http_code:
              type: string
              example: GEN-UNAUTHORIZED
            message:
              type: string
              example: Unauthorized.
    Address:
      type: object
      description: The destination's address.
      properties:
        address1:
          type: string
          example: 123 Main St
          description: The street address of the destination.
        address2:
          type:
            - string
            - "null"
          example: Unit 456
          description: The secondary address details of the destination.
        city:
          type: string
          example: Columbus
        state:
          type:
            - string
            - "null"
          example: Ohio
        zip:
          type:
            - string
            - "null"
          example: '43210'
        country:
          type: string
          example: United States
        country_code:
          type: string
          example: US
securitySchemes:
  api_key:
    type: apiKey
    name: X-Authorization
    in: header

```

--------------------------------

### Initialize Draft Return

Source: https://docs.loopreturns.com/return-create-api/eligibility-api

Use this endpoint to start a draft return by providing shop ID, order name, and other relevant details. The response includes item eligibility status.

```curl
curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{ \
  "shop_id": 23141001, \
  "order_name": "#1001", \
  "secondary_input": "90210", \
  "is_gift": false \
}'
```

--------------------------------

### Create Customer

Source: https://docs.loopreturns.com/api-reference/latest/customers/create-customer

Creates a new customer record in the system.

```APIDOC
## POST /customers

### Description
Creates a new customer.

### Method
POST

### Endpoint
/customers

### Request Body
This endpoint expects a JSON object representing the customer to be created. The exact fields are not specified in the source, but typically include name, email, and address information.

### Response
#### Success Response (201 Created)
Returns the newly created customer object, including its unique identifier.

#### Error Response
- **400 Bad Request**: If the request body is invalid or missing required fields.
- **409 Conflict**: If a customer with the same identifier already exists.
```

--------------------------------

### Get Order by ID (OpenAPI Specification)

Source: https://docs.loopreturns.com/api-reference/latest/orders/get-order

This OpenAPI 3.1.0 specification defines the GET /orders/{id} endpoint for retrieving order details. It includes parameters, response schemas, and error codes.

```yaml
openapi: 3.1.0
info:
  title: Orders API
  version: v1
  description: The Orders API allows managing your shop's orders within the Loop Platform.
  contact:
    name: Loop Returns
    url: https://loopreturns.com/
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Orders
paths:
  /orders/{id}:
    get:
      tags:
        - Orders
      summary: Get Order
      description: Get details about a specific order.
      operationId: get-order
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Identifier of the order.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - read: []
components:
  schemas:
    OrderResponse:
      title: OrderResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          examples:
            - 810772123123123
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type: string
        source:
          type:
            - string
            - 'null'
        channel:
          type: object
          properties:
            id:
              type: integer
              description: The global identifier of the customer.
              examples:
                - 123123123123123
            name:
              type: string
              description: The name of the channel.
        customer:
          type: object
          properties:
            id:
              type: integer
              description: The global identifier of the customer.
              examples:
                - 123123123123123
            external_id:
              type:
                - string
                - 'null'
              examples:
                - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
            phone:
              type: string
        status:
          type: string
          enum:
            - active
            - archived
            - cancelled
            - unknown
          description: Status of the Order.
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        taxes_included:
          type: boolean
        total_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents, with its
            corresponding currency.
        total_price_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents. This is
            included if the price was shown to the customer in an alternate
            currency.
        total_discounts:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards.
        total_discounts_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards. This price is
            discounted from the original price according to the customer's local
            currency.
        shipping_lines:
          $ref: '#/components/schemas/ShippingLines'
          description: The shipping lines for the order.
        order_discounts:
          $ref: '#/components/schemas/OrderDiscounts'
          description: The discounts for the order.
        total_taxes:
          $ref: '#/components/schemas/MoneySet'
          description: The tax amount for the order.
        total_taxes_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >-
            The tax amount for the order according to the customer's local
            currency.
        tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagRequestData'
        refunds:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/RefundData'
        line_items:
          type: array
          items:

```

--------------------------------

### Order Creation with Checkout+ Data

Source: https://docs.loopreturns.com/integration-guides/checkout-plus

When an order is created, push it to the Loop Order API including the accepted offer mode and the session ID from the Checkout+ analysis.

```shell
curl -X POST \
  https://api.loopreturns.com/api/v1/orders \
  -H "X-Authorization: YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "order_id": "YOUR_PLATFORM_ORDER_ID", 
    "customer": { 
      "email": "customer@example.com" 
    }, 
    "fees": [ 
      { 
        "amount": 200, 
        "accepted_offer_mode": [ 
          "shipping", 
          "return" 
        ] 
      } 
    ], 
    "metadata": { 
      "session_id": "CHECKOUT_PLUS_SESSION_ID" 
    } 
  }'
```

--------------------------------

### Get Product OpenAPI Specification

Source: https://docs.loopreturns.com/api-reference/latest/products/get-product

This OpenAPI 3.1.0 specification defines the 'GET /products/{id}' endpoint for retrieving product details. It includes parameters, responses, and schema definitions for product data.

```yaml
openapi: 3.1.0
info:
  title: Products API
  version: v1
  description: >-
    The Products API allows managing your shop's products within the Loop
    Platform.
  contact:
    name: Loop Returns
    url: https://loopreturns.com/
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Products
  - name: Product Variants
paths:
  /products/{id}:
    parameters:
      - schema:
          type: integer
        name: id
        in: path
        required: true
        description: The product's unique identifier.
    get:
      tags:
        - Products
      summary: Get Product
      description: Get the details about a single product.
      operationId: get-product
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/ProductResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - read: []
components:
  schemas:
    ProductResponse:
      title: ProductResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          examples:
            - 810772
          readOnly: true
          description: The unique integer identifier for the product, created by Loop.
        external_id:
          type:
            - string
            - 'null'
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
          description: The identifier used by an external source to identify the product.
        channel:
          type:
            - object
            - 'null'
          description: The name of the channel.
        sku:
          type:
            - string
            - 'null'
          examples:
            - SHOES-US44-M-Brwn
          description: The SKU of the product.
        name:
          type: string
          description: The name of the product.
          examples:
            - Classic Brown Dress Shoes
        weight_grams:
          type:
            - integer
            - 'null'
          format: int32
          examples:
            - 440
          description: The weight of the product in grams.
        barcode:
          type:
            - string
            - 'null'
          examples:
            - 712345000019
          description: The barcode of the product.
        description:
          maxLength: 65000
          type:
            - string
            - 'null'
          description: The description of the product.
        type:
          type:
            - string
            - 'null'
          examples:
            - shoes
          description: >-
            The "type" of the product. This is a single value used to classify
            and group similar products.
        vendor:
          type:
            - string
            - 'null'
          examples:
            - Internal
          description: The manufacturer or seller of the product.
        price:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >-
            The price of the product in minor units, such as cents, with its
            corresponding currency.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2023-04-25T13:25:00-05:00'
          description: The date and time at which the product was created.
        updated_at:
          type:
            - string
            - 'null'
          examples:
            - '2023-04-25T13:45:00-05:00'
          format: date-time
          description: >-
            The date and time at which the product was updated. The value must
            be equal to or greater than `created_at`.
        collections:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Collection'
          description: >-
            A grouping of products which can be used to organize a merchant's
            shop.
        options:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ProductOption'
          description: >-
            An array of optional features or characteristics of the product that
            can be selected by the customer.
        images:
          type:
            - array
            - 'null'
          items:
            type: string
            format: uri
            examples:
              - https://example.com/example.jpg
          description: An array of links to images of the product.
        tags:
          type:
            - array
            - 'null'
          items:
            type: string

```

--------------------------------

### Get Allowlist Item OpenAPI Specification

Source: https://docs.loopreturns.com/api-reference/latest/allowlist/get-allowlist-item

This OpenAPI 3.1.0 specification defines the GET /allowlists/{id} endpoint for retrieving a single allowlist entry. It details parameters, responses, and security requirements.

```yaml
openapi: 3.1.0
info:
  title: Listings API
  description: >-
    Loop Listings can be utilized to allow exceptions and prevent returns in
    specific situations. This API can be used to manage your shop's listings.
  version: v1
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Blocklist
  - name: Allowlist
paths:
  /allowlists/{id}:
    get:
      tags:
        - Allowlist
      summary: Get Allowlist Item
      description: |
        Retrieve an allowlist entry.

        ### Required API key scope
        - Orders
      operationId: getAllowlistItem
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the allowlist entry.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowlistEntryWithCreatedAtResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
      security:
        - api_key: []
components:
  schemas:
    AllowlistEntryWithCreatedAtResponse:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the allowlist entry.
        type:
          $ref: '#/components/schemas/AllowlistValueType'
        value:
          type: string
          examples:
            - example@example.com
          description: >-
            The allowed value. Returns made using this value will override any
            other return ineligibility.
        secondary_value:
          type: string
          examples:
            - example.2@example.com
          description: This value is not used.
        created_at:
          type: string
          examples:
            - '2023-06-09 00:00:00'
          description: >-
            The date and time at which the entry was created, using the ISO 8601
            date format.
    UnauthorizedResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
                - '401'
            http_code:
              type: string
              examples:
                - GEN-UNAUTHORIZED
            message:
              type: string
              examples:
                - Unauthorized.
    NotFoundResponse:
      type: object
      properties:
        error:
          description: >-
            The error message returned when a blocklist entry associated with
            the given `id` can't be found.
          type: string
          examples:
            - Listing not found
    AllowlistValueType:
      type: string
      description: >-
        The type of value allowed by this allowlist entry. `order` is the order
        number of the allowed order and `email` is the customer's email address.
      enum:
        - order
        - email
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

```