ReturnLogic API (V1)

Download OpenAPI specification:Download

Getting Started

Authentication

The ReturnLogic API uses bearer tokens to authenticate requests. You must pass the token in the Authorization HTTP request header.

Authorization: Bearer {{your token here}}

Public Apps - Authorization Code Flow

Your public app must have a redirect url that is set up to accept the following query string parameters:

  • code - The authorization code generated after a successful installation
  • teamId - The unique identifier of the retailer that installed your app

Whenever a retailer installs your app, we will redirect the retailer to your URL with the auth code and the teamId appended in the query string.

https://www.your-public-app.com/app/authorize_redirect?code=a22bcde12345&teamId=36bd1371-1eac-40d3-92f4-065982ff9d3f

Use the code provided and make an HTTP POST request to https://api.returnlogic.com/v1/oauth with the following body:

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "a22bcde12345"  
}

You'll receive a Bearer token and a Refresh token:

{
  "bearer_token": "uebjkefgh84372",
  "refresh_token": "buelfxkdezxc10392"
}

The bearer token can be used to make API requests. The refresh token can be used to generate new bearer tokens when they expire.

It is your responsibility to keep track of bearer tokens for each retailer that installs your application.

WebHooks - Overview

Webhooks allow a developer to register with our systems requesting to be notified when specific actions or events occur in the ReturnLogic environment. When a developer has subscribed to an action our system will notify the developer's application at the endpoint they defined providing a payload of data about the event. This payload allows their application to be aware of the actions, such as a new RMA being created, updated, or deleted. This sequence enables a developer to have their application respond to an event in our platform in near real-time if their endpoint is reachable.

Things to keep in mind about webhooks.

Order is not guaranteed - The order webhooks are delivered is not guaranteed. They will be delivered based on queue and retry attempts.

Delivery is not guaranteed - While our system will make every attempt to deliver a webhook message, we can not guarantee delivery or receipt of a delivery. Developers should never assume that all notifications will make it to their endpoint 100% of the time. Delivery failures are typically caused by our system's inability to contact the registered endpoint. Generally, this is due to an invalid endpoint URI definition or an internet connectivity problem between the two systems.

How messages are delivered - While the exact time to delivery will depend on several factors, such as the connection between our servers and the endpoint the developer registers, delivery is sent in the following manner.

  • Retries start after a delivery failure and will continue periodically for a 24-hour period after which the message will be discarded.
  • If 100 messages have been discarded, the system will automatically deactivate the registration. When this happens, no messages will be sent to that endpoint until the developer updates the registration setting it back to a active status. Any messages that would have sent to the endpoint while it is in a deactivated status will not be delivered. Only messages generated after the endpoint is updated back to an active status will be queued and delivered by the webhook system. Running a list webhooks API call will provide a status of which registrations are active or inactive. Editing the affected endpoint registration and setting the active parameter value to true will reset the error count and once again enable the registration.

Error Codes

Any API call could return an error:

  • 401 - Unauthorized
  • 400 - Bad Request
  • 429 - Rate Limit Exceeded
  • 503 - Down For Maintenance

Rate Limiting

The default rate limit for a ReturnLogic API key is 2 requests per second and 120 requests per minute. If an API request exceeds the rate limit, the API will return a 429 Rate Limit Exceeded response. The following HTTP headers will be present on all API responses to help you stay within the limit.

  • X-RateLimit-Limit-Second: maximum number of calls client can make in 1 second
  • X-RateLimit-Limit-Minute: maximum number of calls client can make in 1 minute
  • X-RateLimit-Remaining-Second: remaining number of calls client can make in 1 second
  • X-RateLimit-Remaining-Minute: remaining number of calls client can make in 1 minute

Order

List Orders

Get a list of Orders

query Parameters
skip
integer <int32> >= 0
Default: 0

Number of items to skip over

limit
integer <int32> [ 1 .. 250 ]
Default: 20

Limit on number of items to return

orderNumber
string

Find Orders by order number

orderName
string

Find Orders by order name

email
string

Find Orders by email address. Case insensitive, exact match only.

minCreateDate
string <date-time>

Find Orders created on or after this date

maxCreateDate
string <date-time>

Find Orders created on or before this date

financialStatus
string (OrderFinancialStatus)
Enum: "authorized" "paid" "partially_paid" "pending" "refunded" "voided" "ThirdParty"

Find Orders by their financial status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Order

Create a new order

Request Body schema: application/json
required
externalOrderId
required
string

The ID of the order on the ecommerce platform (i.e. Shopify)

externalCustomerId
number <double>

The ID of the customer who placed the order on the ecommerce platform (i.e. Shopify)

customerEmail
string

The email provided when creating this order.

customerPhone
string

The customer phone provided when creating this order.

orderNumber
required
string

Order number provided to the customer to identify the order. Used to initiate RMAs.

orderName
required
string

Order name provided to the customer to identify the order. Can be used to initiate RMAs.

object (Address)
object (Address)
fulfillmentStatus
string (OrderFulfillmentStatus)
Enum: "fulfilled" "partial" "restocked"
financialStatus
string (OrderFinancialStatus)
Enum: "authorized" "paid" "partially_paid" "pending" "refunded" "voided" "ThirdParty"
externalSource
string

Name of ecommerce platform where order was originally created

sourceType
string

How the order was collected, i.e. web, pos, in-store

shippedAt
string <date-time>

Date the order was shipped.

tags
required
Array of strings

A list of tags on the order.

taxesIncluded
required
boolean

Are taxes included in the price of the order items.

shopCurrencyCode
required
string <= 3 characters

3 letter code of the currency used by the store.

totalPrice
required
number <double>

Amount billed to customer after applying discounts, taxes, shipping, and other fees

fees
required
number <double>

Additional fees added to order not reported on order items

taxPrice
required
number <double>

Amount of tax applied to order

shippingPrice
required
number <double>

Cost of shipping

refundAmount
required
number <double>

Total value refunded to order

externalCreateDate
string <date-time>

Date order was created on ecommerce platform

externalUpdateDate
string <date-time>

Date order was updated on ecommerce platform

gateway
string

Payment gateway used to process the order

flatRateBonusCreditApplied
boolean

A flat rate bonus credit was applied to a return request; this value ensures that a flat rate bonus credit can only be applied once per order

Array of AddProductToOrderRequest (object) or AddCustomItemToOrderRequest (object) (AddOrderItemToOrderRequest)

Array of order items to create

Array of objects (OrderDiscountAttributes)

Array of order discounts to create

Responses

Request samples

Content type
application/json
{
  • "externalOrderId": "string",
  • "externalCustomerId": 0,
  • "customerEmail": "string",
  • "customerPhone": "string",
  • "orderNumber": "string",
  • "orderName": "string",
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "fulfillmentStatus": "fulfilled",
  • "financialStatus": "authorized",
  • "externalSource": "string",
  • "sourceType": "string",
  • "shippedAt": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "taxesIncluded": true,
  • "shopCurrencyCode": "str",
  • "totalPrice": 0,
  • "fees": 0,
  • "taxPrice": 0,
  • "shippingPrice": 0,
  • "refundAmount": 0,
  • "externalCreateDate": "2019-08-24T14:15:22Z",
  • "externalUpdateDate": "2019-08-24T14:15:22Z",
  • "gateway": "string",
  • "flatRateBonusCreditApplied": true,
  • "orderItems": [
    ],
  • "orderDiscounts": [
    ]
}

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Count Orders

Count total number of Orders

query Parameters
orderNumber
string

Find Orders by their order number

orderName
string

Find Orders by their order name

email
string

Find Orders associated with an email address

minCreateDate
string <date-time>

Find Orders created on or after this date

maxCreateDate
string <date-time>

Find Orders created on or before this date

financialStatus
string (OrderFinancialStatus)
Enum: "authorized" "paid" "partially_paid" "pending" "refunded" "voided" "ThirdParty"

Find Orders by their financial status

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get Order

Get single order

path Parameters
rlOrderId
required
integer <int32>

Order ID

Responses

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Update Order

Update an existing order. Cannot change monetary values after an RMA has been created.

path Parameters
rlOrderId
required
integer <int32>

Order ID

Request Body schema: application/json
required
customerEmail
string

The email provided when creating this order.

customerPhone
string or null

The customer phone provided when creating this order.

object (Address)
object (Address)
fulfillmentStatus
string or null
Enum: "fulfilled" "partial" "restocked"

Order fulfillment status

financialStatus
string (OrderFinancialStatus)
Enum: "authorized" "paid" "partially_paid" "pending" "refunded" "voided" "ThirdParty"
sourceType
string

How the order was collected, i.e. web, pos, in-store

shippedAt
string or null <date-time>

Date the order was shipped.

tags
Array of strings

A list of tags on the order.

taxesIncluded
boolean

Are taxes included in the price of the order items.

shopCurrencyCode
string <= 3 characters

3 letter code of the currency used by the store.

totalPrice
number <double>

Amount billed to customer after applying discounts, taxes, shipping, and other fees

fees
number <double>

Additional fees added to order not reported on order items

taxPrice
number <double>

Amount of tax applied to order

shippingPrice
number <double>

Cost of shipping

refundAmount
number <double>

Total value refunded to order

externalUpdateDate
string <date-time>

Date order was updated on ecommerce platform

gateway
string or null

Payment gateway used to process the order

Responses

Request samples

Content type
application/json
{
  • "customerEmail": "string",
  • "customerPhone": "string",
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "fulfillmentStatus": "fulfilled",
  • "financialStatus": "authorized",
  • "sourceType": "string",
  • "shippedAt": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "taxesIncluded": true,
  • "shopCurrencyCode": "str",
  • "totalPrice": 0,
  • "fees": 0,
  • "taxPrice": 0,
  • "shippingPrice": 0,
  • "refundAmount": 0,
  • "externalUpdateDate": "2019-08-24T14:15:22Z",
  • "gateway": "string"
}

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Add Order Item

Add an order item to an existing order

path Parameters
rlOrderId
required
integer <int32>

Order ID

Request Body schema: application/json
required
Any of
externalOrderItemId
required
string

The ID of the order item on the ecommerce platform

quantity
required
integer <int32>

The quantity of product on this order item

isTaxable
required
boolean

Is this order item taxable

isGiftCard
required
boolean

Is this order item a gift card

taxPerItem
required
number <double>

Tax per item

vendor
string

Order item vendor

fulfillmentService
string

Order item fulfillment service

fulfillmentStatus
string (OrderFulfillmentStatus)
Enum: "fulfilled" "partial" "restocked"
fulfillableQuantity
number <double>

Quantity on order line that have not yet been fulfilled

properties
Array of strings

List of properties assigned to the order line

refundQuantity
number <double>

Quantity on order line that have been refunded

Array of objects (OrderDiscountAttributes)

Discounts applied to order item

rlProductVariantId
required
number <double>

Product variant ID on ReturnLogic of variant associated with order item

priceOverride
number <double>

Price to use instead of the catalog price

Responses

Request samples

Content type
application/json
Example
{
  • "externalOrderItemId": "string",
  • "quantity": 0,
  • "isTaxable": true,
  • "isGiftCard": true,
  • "taxPerItem": 0,
  • "vendor": "string",
  • "fulfillmentService": "string",
  • "fulfillmentStatus": "fulfilled",
  • "fulfillableQuantity": 0,
  • "properties": [
    ],
  • "refundQuantity": 0,
  • "orderItemDiscounts": [
    ],
  • "rlProductVariantId": 0,
  • "priceOverride": 0
}

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Update Order Item

Update an existing order item. Cannot change monetary values after an RMA has been created.

path Parameters
rlOrderId
required
integer <int32>

Order ID

rlOrderItemId
required
number <double>

Order Item ID

Request Body schema: application/json
required

EditOrderItemRequest

quantity
integer <int32>

The quantity of product on this order item

isTaxable
boolean

Is this order item taxable

isGiftCard
boolean

Is this order item a gift card

taxPerItem
number <double>

Tax per item

vendor
string

Order item vendor

fulfillmentService
string

Order item fulfillment service

fulfillmentStatus
string (OrderFulfillmentStatus)
Enum: "fulfilled" "partial" "restocked"
fulfillableQuantity
number <double>

Quantity on order line that have not yet been fulfilled

properties
Array of strings

List of properties assigned to the order line

refundQuantity
number <double>

Quantity on order line that have been refunded

Responses

Request samples

Content type
application/json
{
  • "quantity": 0,
  • "isTaxable": true,
  • "isGiftCard": true,
  • "taxPerItem": 0,
  • "vendor": "string",
  • "fulfillmentService": "string",
  • "fulfillmentStatus": "fulfilled",
  • "fulfillableQuantity": 0,
  • "properties": [
    ],
  • "refundQuantity": 0
}

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Remove Order Item

Removes an order item from an order. Cannot delete an order item that is part of an RMA.

path Parameters
rlOrderId
required
integer <int32>

Order ID

rlOrderItemId
required
integer <int32>

Order Item ID

Responses

Response samples

Content type
application/json
{
  • "rlOrderId": 87654,
  • "externalOrderId": "1456032",
  • "externalSource": "Shopify",
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "externalCreateDate": "2024-05-11T19:53:05.695Z",
  • "externalUpdateDate": "2024-05-13T19:53:05.695Z",
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "customerEmail": "admin@returnlogic.com",
  • "customerPhone": "111-111-1111",
  • "orderName": "RL1234",
  • "orderNumber": "1234",
  • "gateway": "Paypal",
  • "flatRateBonusCreditApplied": false,
  • "subtotalPrice": 30.5,
  • "totalPrice": 40,
  • "shippingPrice": 5.95,
  • "fees": 0,
  • "orderLevelDiscount": 0,
  • "taxPrice": 3.55,
  • "taxesIncluded": false,
  • "refundAmount": 0,
  • "shippedAt": "2024-05-12T19:53:05.695Z",
  • "shopCurrencyCode": "USD",
  • "tags": [ ],
  • "fulfillmentStatus": "fulfilled",
  • "isPseudo": false,
  • "discounts": [
    ],
  • "orderItems": [
    ]
}

Product Category

Add Product To Category

Add a single product to a category

path Parameters
rlProductCategoryId
required
integer <int32>

RL Product Category ID

rlProductId
required
integer <int32>

RL Product ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProductCategoryId": 0,
  • "rlProducts": [
    ]
}

Remove Product From Category

Removes a single product from a category

path Parameters
rlProductCategoryId
required
integer <int32>

RL Product Category ID

rlProductId
required
integer <int32>

RL Product ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProductCategoryId": 0,
  • "rlProducts": [
    ]
}

Count Category Products

Count total number of Products For Category

path Parameters
categoryId
required
integer <int32>

Find only Products in category

query Parameters
sku
string

Find only Products with variants matching sku

status
string (ProductStatus)
Enum: "active" "inActive" "any"

Find only Products active/inActive/any

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

List Category Products

Get the list of Products inside a category

path Parameters
categoryId
required
integer <int32>

Find only Products in category

query Parameters
sku
string

Find only Products with variants matching sku

status
string (ProductStatus)
Enum: "active" "inActive" "any"

Find only Products active/inActive/any

skip
integer <int32> >= 0
Default: 0

Number of items to skip over

limit
integer <int32> [ 1 .. 250 ]
Default: 20

Limit on number of items to return

Responses

Request samples

curl api.returnlogic.com/v1/productCategories/{categoryId}/products\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
[
  • {
    }
]

Count Product Categories

Get the count of Products Categories

query Parameters
name
string

to search product category by

externalCategoryIds
Array of strings

Find categories matching a list of ids from an external source

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get Product Category

Get a single product category by ID

path Parameters
rlProductCategoryId
required
integer <int32>

Product Category ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProductCategoryId": 0,
  • "rlProducts": [
    ]
}

Update Product Category

Partially update an existing a product category.

path Parameters
rlProductCategoryId
required
integer <int32>

ReturnLogic Product Category ID

Request Body schema: application/json
required

Product Category Properties to Update

name
string

Product Category Name

imageUrl
string

Full URL to Product Category Image

imageAlt
string

Alt text for Product Category Image

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "imageUrl": "string",
  • "imageAlt": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProductCategoryId": 0,
  • "rlProducts": [
    ]
}

List Product Categories

Get the list of Products Categories

query Parameters
name
string

to search product category by

externalCategoryIds
Array of strings

Find categories matching a list of ids from an external source

skip
integer <int32> >= 0
Default: 0

Number of items to skip over

limit
integer <int32> [ 1 .. 250 ]
Default: 10

Limit on number of items to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Product Category

Creates a product category containing products.

Request Body schema: application/json
required

Product Category Creation Attributes

name
required
string

Product Category Name

externalCategoryId
required
string

External ID of category from eCommerce platform

imageUrl
string

Full URL of category image to display to users

imageAlt
string

Image alt text

Array of objects (CreateProductCategoryItem)

Optional ReturnLogic Product IDs to add upon creation of category

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProducts": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "externalCategoryId": "string",
  • "imageUrl": "string",
  • "imageAlt": "string",
  • "rlProductCategoryId": 0,
  • "rlProducts": [
    ]
}

Product

Update Product

Update Product

path Parameters
rlProductId
required
integer <int32>

ReturnLogic Product ID

Request Body schema: application/json
required

Attributes to update on RL Product

isActive
boolean

Setting this to false will 'soft delete' the product, effectively removing it from ReturnLogic. If it was purchased, it will still show up in existing orders.

externalProductId
string

The ID of the product in the ecommerce platform

name
string

Product name

inventoryQuantity
integer <int32>

Total product inventory

price
number <double>

Product price

vendor
string

Vendor, such as original manufacturer, wholesaler, etc.

productType
string

Product Type

tags
Array of strings

Tags

imageUrl
string

Full URL to product image

Array of objects (UpdateProductOption)

ReturnLogic Product Options

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "externalProductId": "string",
  • "name": "string",
  • "inventoryQuantity": 0,
  • "price": 0,
  • "vendor": "string",
  • "productType": "string",
  • "tags": [
    ],
  • "imageUrl": "string",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "isActive": true,
  • "rlProductId": 534122,
  • "name": "Practical Steel Chair",
  • "vendor": "Returnlogic",
  • "tags": [
    ],
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "variants": [
    ],
  • "isDeleted": false,
  • "isPublic": true
}

Get Product

Get Single Product

path Parameters
rlProductId
required
integer <int32>

Product identifier

Responses

Request samples

curl api.returnlogic.com/v1/products/{rlProductId}\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
{
  • "isActive": true,
  • "rlProductId": 534122,
  • "name": "Practical Steel Chair",
  • "vendor": "Returnlogic",
  • "tags": [
    ],
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "variants": [
    ],
  • "isDeleted": false,
  • "isPublic": true
}

List Products

Get the list of Products

query Parameters
sku
string

Find only Products with variants matching sku

categoryId
integer <int32>

Find only Products in category

status
string (ProductStatus)
Enum: "active" "inActive" "any"

Find only Products active/inActive/any

externalProductIds
Array of strings

Find products matching a list of ids from an external source

skip
integer <int32> >= 0
Default: 0

Number of items to skip over

limit
integer <int32> [ 1 .. 250 ]
Default: 20

Limit on number of items to return

Responses

Request samples

curl api.returnlogic.com/v1/products\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
[
  • {
    }
]

Create Product

Creates a product within ReturnLogic

Request Body schema: application/json
required
isActive
required
boolean

Setting this to false will 'soft delete' the product, effectively removing it from ReturnLogic. If it was purchased, it will still show up in existing orders.

externalProductId
required
string

External ID from ecommerce system

name
string

Product name

vendor
required
string

Vendor, such as original manufacturer, wholesaler, etc.

productType
string

Product Type

tags
Array of strings

Tags

imageUrl
string

Full URL to product image

productCreatedAt
string <date-time> (IsoDate)

ISO-8601 Date time

productUpdateAt
string <date-time> (IsoDate)

ISO-8601 Date time

Array of objects (CreateProductWithOption)

Product Options (Size, Material, Color)

required
Array of objects (CreateRlVariantReq) non-empty

Product Variants. Products without options must have one variant.

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "externalProductId": "string",
  • "name": "string",
  • "vendor": "string",
  • "productType": "string",
  • "tags": [
    ],
  • "imageUrl": "string",
  • "productCreatedAt": "YYYY-MM-DDThh:mm:ss",
  • "productUpdateAt": "YYYY-MM-DDThh:mm:ss",
  • "options": [
    ],
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "isActive": true,
  • "rlProductId": 534122,
  • "name": "Practical Steel Chair",
  • "vendor": "Returnlogic",
  • "tags": [
    ],
  • "createDate": "2024-05-11T19:53:05.695Z",
  • "updateDate": "2024-05-13T19:53:05.695Z",
  • "variants": [
    ],
  • "isDeleted": false,
  • "isPublic": true
}

Count Products

Count total number of Products

query Parameters
sku
string

Find only Products with variants matching sku

categoryId
integer <int32>

Find only Products in category

status
string (ProductStatus)
Enum: "active" "inActive" "any"

Find only Products active/inActive/any

Responses

Request samples

curl api.returnlogic.com/v1/products/count\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
{
  • "count": 0
}

Update Variant

Partial update for a product variant

path Parameters
rlProductId
required
integer <int32>

ReturnLogic Product ID

rlProductVariantId
required
integer <int32>

ReturnLogic Variant ID

Request Body schema: application/json
required

Attributes to update on RL Variant

isActive
boolean

Whether the product can be searched for and selected by customers for a return.

externalVariantId
string

External Variant ID from ecommerce platform

position
integer <int32>

Variant display position. Useful for sorting.

sku
string

SKU of specific product variant.

name
string

Name of variant

price
number <double>

Price of variant

grams
integer <int32>

Weight in grams

weight
number <double>

Original weight entered.

weightUnit
string (MassUnit)
Enum: "lb" "g" "kg" "oz"
barcode
string

Base64 Barcode value to be used

fulfillmentService
string

Name of service used to fulfill orders containing this variant.

inventoryQuantity
integer <int32>

Total product inventory

inventoryItemId
integer <int32>

External ID used for inventory purposes such as restocking.

imageUrl
string

Full URL to image of product variant

variantUpdatedAt
string <date-time> (IsoDate)

ISO-8601 Date time

Array of objects (VariantOptionAttributes)

Variant Options

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "externalVariantId": "string",
  • "position": 0,
  • "sku": "string",
  • "name": "string",
  • "price": 0,
  • "grams": 0,
  • "weight": 0,
  • "weightUnit": "lb",
  • "barcode": "string",
  • "fulfillmentService": "string",
  • "inventoryQuantity": 0,
  • "inventoryItemId": 0,
  • "imageUrl": "string",
  • "variantUpdatedAt": "YYYY-MM-DDThh:mm:ss",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "isActive": true,
  • "externalVariantId": "string",
  • "position": 0,
  • "sku": "string",
  • "name": "string",
  • "price": 0,
  • "grams": 0,
  • "weight": 0,
  • "weightUnit": "lb",
  • "barcode": "string",
  • "fulfillmentService": "string",
  • "inventoryQuantity": 0,
  • "inventoryItemId": 0,
  • "imageUrl": "string",
  • "variantCreatedAt": "YYYY-MM-DDThh:mm:ss",
  • "variantUpdatedAt": "YYYY-MM-DDThh:mm:ss",
  • "createDate": "YYYY-MM-DDThh:mm:ss",
  • "updateDate": "YYYY-MM-DDThh:mm:ss",
  • "rlProductVariantId": 0,
  • "rlProductId": 0,
  • "options": [
    ]
}

Create Variant

Add new variant to product. Variant Option values are required for products with options.

path Parameters
rlProductId
required
integer <int32>

ReturnLogic Product ID

Request Body schema: application/json
required

Creation attributes for Product Variant

isActive
required
boolean

Whether the product can be searched for and selected by customers for a return.

externalVariantId
required
string

External Variant ID from ecommerce platform

position
required
integer <int32>

Variant display position. Useful for sorting.

sku
required
string

Sku The variant's sku.

name
required
string

Name. The name of the variant, the name is required.

price
number <double>

Price of variant

grams
integer <int32>

Weight in grams

weight
required
number <double>

Weight of item before packing. Any of the allowed MassUnits can be specified using the weightUnit field.

weightUnit
required
string (MassUnit)
Enum: "lb" "g" "kg" "oz"
barcode
string

Base64 Barcode value to be used

fulfillmentService
string

Name of service used to fulfill orders containing this variant.

inventoryQuantity
required
integer <int32>

Total product inventory

inventoryItemId
integer <int32>

External ID used for inventory purposes such as restocking.

imageUrl
string

Full URL to image of product variant

variantCreatedAt
string <date-time> (IsoDate)

ISO-8601 Date time

variantUpdatedAt
string <date-time> (IsoDate)

ISO-8601 Date time

Array of objects (CreateVariantWithOption)

Variant Option Values If the product is being created with options, you must specify variant option values for every option.

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "externalVariantId": "string",
  • "position": 0,
  • "sku": "string",
  • "name": "string",
  • "price": 0,
  • "grams": 0,
  • "weight": 0,
  • "weightUnit": "lb",
  • "barcode": "string",
  • "fulfillmentService": "string",
  • "inventoryQuantity": 0,
  • "inventoryItemId": 0,
  • "imageUrl": "string",
  • "variantCreatedAt": "YYYY-MM-DDThh:mm:ss",
  • "variantUpdatedAt": "YYYY-MM-DDThh:mm:ss",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "isActive": true,
  • "externalVariantId": "string",
  • "position": 0,
  • "sku": "string",
  • "name": "string",
  • "price": 0,
  • "grams": 0,
  • "weight": 0,
  • "weightUnit": "lb",
  • "barcode": "string",
  • "fulfillmentService": "string",
  • "inventoryQuantity": 0,
  • "inventoryItemId": 0,
  • "imageUrl": "string",
  • "variantCreatedAt": "YYYY-MM-DDThh:mm:ss",
  • "variantUpdatedAt": "YYYY-MM-DDThh:mm:ss",
  • "createDate": "YYYY-MM-DDThh:mm:ss",
  • "updateDate": "YYYY-MM-DDThh:mm:ss",
  • "rlProductVariantId": 0,
  • "rlProductId": 0,
  • "options": [
    ]
}

RMA

Get RMAs

Get a list of RMAs

Datetime format is ISO-8601 as defined in RFC 3339

Query Params that accept multiple strings should be formatted as comma-separated values

query Parameters
minCreateDate
string <date-time> (IsoDate)
Example: minCreateDate=YYYY-MM-DDThh:mm:ss

Find RMAs created on or after this date

maxCreateDate
string <date-time> (IsoDate)
Example: maxCreateDate=YYYY-MM-DDThh:mm:ss

Find RMAs created on or before this date

workflowStatus
Array of strings (RmaWorkflowStatusKey)
Items Enum: "Abandoned" "Requested" "Authorized" "Canceled" "InTransit" "Delivered" "Active" "Received" "Processed" "Complete" "Rejected"
Example: workflowStatus=Requested,Authorized

Find only RMAs with workflowStatus in list

returnType
Array of strings (RmaReturnType)
Items Enum: "exchange" "warranty" "refund" "giftcard"
Example: returnType=exchange,warranty

Find only RMAs with returnType in list

returnReasonCode
Array of strings
Example: returnReasonCode=SZ,QTY

Find only RMAs with return reason in list

email
Array of strings

Find RMAs by the rma email or order email. Case insensitive, exact match.

orderName
string

Find only RMAs with orderName

externalOrderNumber
string

Find RMAs by their associated external order number

showArchived
boolean

Find only archived or non-archived RMAs

thirdPartyOnly
boolean

Find only third party RMAs

requiresAction
boolean

Find RMAs that aren't currently scheduled for automatic processing. If omitted, shows all RMAs.

onlyFlaggedRmas
boolean

Find only RMAs that have been flagged

onlyWarrantyOutOfStock
boolean

Find only RMAs that are flagged with a status code of Contact Customer Support

skip
integer <int32> >= 0
Default: 0

Number of items to skip over

limit
integer <int32> [ 1 .. 250 ]
Default: 20

Limit on number of items to return

Responses

Request samples

curl api.returnlogic.com/v1/rmas\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
[
  • {
    }
]

Count RMAs

Count total number of RMAs

Datetime format is ISO-8601 as defined in RFC 3339

Query Params that accept multiple strings should be formatted as comma-separated values

query Parameters
minCreateDate
string <date-time> (IsoDate)
Example: minCreateDate=YYYY-MM-DDThh:mm:ss

Find RMAs created on or after this date

maxCreateDate
string <date-time> (IsoDate)
Example: maxCreateDate=YYYY-MM-DDThh:mm:ss

Find RMAs created on or before this date

workflowStatus
Array of strings (RmaWorkflowStatusKey)
Items Enum: "Abandoned" "Requested" "Authorized" "Canceled" "InTransit" "Delivered" "Active" "Received" "Processed" "Complete" "Rejected"
Example: workflowStatus=Requested,Authorized

Find only RMAs with workflowStatus in list

returnType
Array of strings (RmaReturnType)
Items Enum: "exchange" "warranty" "refund" "giftcard"
Example: returnType=exchange,warranty

Find only RMAs with returnType in list

returnReasonCode
Array of strings
Example: returnReasonCode=SZ,QTY

Find only RMAs with return reason in list

email
Array of strings

Find RMAs by the rma email or order email. Case insensitive, exact match.

orderName
string

Find only RMAs with orderName

externalOrderNumber
string

Find only RMAs by their associated external order number

showArchived
boolean

Find only archived or non-archived RMAs

thirdPartyOnly
boolean

Find only RMAs where the associated order is from a third party source (i.e. not Shopify)

requiresAction
boolean

Find RMAs that aren't currently scheduled for automatic processing. If omitted, shows all RMAs.

onlyFlaggedRmas
boolean

Find only RMAs that have been flagged

onlyWarrantyOutOfStock
boolean

Find only RMA's that are flagged with a status code of Contact Customer Support

Responses

Request samples

curl api.returnlogic.com/v1/rmas/count\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
{
  • "count": 0
}

Get RMA

Get Single RMA

path Parameters
rlRmaId
required
integer <int32>

RMA identifier

Responses

Request samples

curl api.returnlogic.com/v1/rmas/{rmaId}\
        -H "Authorization: Bearer {{your_api_token}}"\
        

Response samples

Content type
application/json
{
  • "teamId": "a3866686-4a03-4dee-afc4-20dd50762e1c",
  • "rlRmaId": 12345,
  • "rlOrderId": 87654,
  • "externalOrderNumber": "12345678",
  • "orderName": "RL12345678",
  • "rmaEmail": "admin@returnlogic.com",
  • "orderEmail": "admin@returnlogic.com",
  • "orderUrl": "",
  • "fromShipping": {
    },
  • "toShipping": {
    },
  • "workflowStatus": "Delivered",
  • "workflowStatusId": 5,
  • "rowpointer": "394b5b4a-d8d4-45fc-b189-a363cc850955",
  • "orderDate": "2024-03-30T19:53:05.695Z",
  • "rmaExpirationDate": "2024-06-13T19:53:05.695Z",
  • "isThirdParty": false,
  • "receiptImageUrl": "",
  • "isArchived": false,
  • "isAllProcessed": false,
  • "timeline": {
    },
  • "rmaItems": [
    ],
  • "shippingLabel": {},
  • "totals": {
    },
  • "flagged": false
}

Fulfill RMA

Update one or more RMA item(s) for an RMA

Notes:

  • If all RMA items on an RMA are received, then the RMA status will become Received.
  • If your store is configured for Automated Processing for Received and the RMA matches your settings, then the RMA may be automatically processed.
path Parameters
rlRmaId
required
integer <int32>

RMA ID

Request Body schema: application/json
required

RMA Fulfillment data

required
Array of objects (UpdateRmaFulfillmentItem)

Responses

Request samples

Content type
application/json
{
  • "rmaItems": [
    ]
}

Response samples

Content type
application/json
{
  • "teamId": "a3866686-4a03-4dee-afc4-20dd50762e1c",
  • "rlRmaId": 12345,
  • "rlOrderId": 87654,
  • "externalOrderNumber": "12345678",
  • "orderName": "RL12345678",
  • "rmaEmail": "admin@returnlogic.com",
  • "orderEmail": "admin@returnlogic.com",
  • "orderUrl": "",
  • "fromShipping": {
    },
  • "toShipping": {
    },
  • "workflowStatus": "Delivered",
  • "workflowStatusId": 5,
  • "rowpointer": "394b5b4a-d8d4-45fc-b189-a363cc850955",
  • "orderDate": "2024-03-30T19:53:05.695Z",
  • "rmaExpirationDate": "2024-06-13T19:53:05.695Z",
  • "isThirdParty": false,
  • "receiptImageUrl": "",
  • "isArchived": false,
  • "isAllProcessed": false,
  • "timeline": {
    },
  • "rmaItems": [
    ],
  • "shippingLabel": {},
  • "totals": {
    },
  • "flagged": false
}

Flag RMA

Flag the RMA for advanced filtering in the originate and collector lists

Notes: Flagging is useful for raising attention on RMA's that have special exceptions that have to be communicated across the team. Once a RMA is flagged it cannot be unflagged

path Parameters
rlRmaId
required
integer <int32>

RMA ID

Responses

Response samples

Content type
application/json
{
  • "teamId": "a3866686-4a03-4dee-afc4-20dd50762e1c",
  • "rlRmaId": 12345,
  • "rlOrderId": 87654,
  • "externalOrderNumber": "12345678",
  • "orderName": "RL12345678",
  • "rmaEmail": "admin@returnlogic.com",
  • "orderEmail": "admin@returnlogic.com",
  • "orderUrl": "",
  • "fromShipping": {
    },
  • "toShipping": {
    },
  • "workflowStatus": "Delivered",
  • "workflowStatusId": 5,
  • "rowpointer": "394b5b4a-d8d4-45fc-b189-a363cc850955",
  • "orderDate": "2024-03-30T19:53:05.695Z",
  • "rmaExpirationDate": "2024-06-13T19:53:05.695Z",
  • "isThirdParty": false,
  • "receiptImageUrl": "",
  • "isArchived": false,
  • "isAllProcessed": false,
  • "timeline": {
    },
  • "rmaItems": [
    ],
  • "shippingLabel": {},
  • "totals": {
    },
  • "flagged": false
}

RMA Return Type History

Get RMA Return Type History

path Parameters
rlRmaItemId
required
number <double>

RMA Item to retrieve return history for.

Responses

Response samples

Content type
application/json
{
  • "returnTypeId": 0,
  • "functionalReturnTypeId": 0,
  • "returnTypeName": "string",
  • "functionalReturnTypeName": "string",
  • "returnTypeDisplayName": "string",
  • "returnTypeDescription": "string",
  • "returnTypeDisplayDescription": "string",
  • "returnTypeDisplayPosition": 0,
  • "active": true,
  • "isAllowed": true,
  • "returnPeriod": 0,
  • "hasReturnPeriod": true,
  • "returnPeriodMessage": "string",
  • "shippingType": "string",
  • "extendedWarranty": 0,
  • "returnHistory": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

WebHooks

List WebHook Registrations

List all web hook registrations for the current private application.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add WebHook Registration

Add a webhook registration for the current private application.

Request Body schema: application/json
required
resourceAction
required
string (WebHookNotificationApiResourceAction)
Enum: "rma.updated" "rma.requested" "rma.deleted"

Available Notification.

endpoint
required
string

Endpoint where notification should be posted to.

active
boolean

Is registration Active or Disabled?

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "registrationId": "string",
  • "resourceAction": "string",
  • "endpoint": "string",
  • "active": true,
  • "createDate": "2019-08-24T14:15:22Z"
}

Update WebHook Registration

Update a webhook registration for the current private application.

path Parameters
registrationId
required
string

Unique ID of webhook registration.

Request Body schema: application/json
required
resourceAction
required
string (WebHookNotificationApiResourceAction)
Enum: "rma.updated" "rma.requested" "rma.deleted"

Available Notification.

endpoint
required
string

Endpoint where notification should be posted to.

active
boolean

Is registration Active or Disabled?

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "registrationId": "string",
  • "resourceAction": "string",
  • "endpoint": "string",
  • "active": true,
  • "createDate": "2019-08-24T14:15:22Z"
}