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 at 10 seconds, and each retry increments in the following fashion after the 5th retry; each retry after that is every 120 seconds. Progressive 10/20/30/60/120 seconds (max 120 seconds)
  • Retries continue 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

Exchange

Acknowledge Exchange Success

After a PublicApplication has successfully processed an exchange request, the PublicApplication will acknowledge that the exchange was successful through this endpoint.

path Parameters
rlRmaId
required
integer <int32>

RMA identifier

Request Body schema: application/json
action
required
string (WebHookNotificationAction)
Enum: "requested" "authorized" "canceled" "rejected" "inTransit" "delivered" "received" "completed" "active" "approved" "processed" "archived" "deleted" "updated" "ProcessRefund" "ProcessGiftCard" "ProcessExchange" "ProcessWarranty" "ProcessRestock"

Subtype of Notification.

rlRmaId
required
number <double>
correlationId
required
string
Array of objects (ExternalProcessingActionError)
object (EcommerceExchangeTotalsResponse)

Responses

Request samples

Content type
application/json
{
  • "action": "requested",
  • "rlRmaId": 0,
  • "correlationId": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "received": true,
  • "errors": [
    ]
}

Acknowledge Exchange Failure

After a PublicApplication has failed to process an exchange request, the PublicApplication will acknowledge that the exchanged failed through this endpoint.

path Parameters
rlRmaId
required
integer <int32>

RMA identifier

Request Body schema: application/json
action
required
string (WebHookNotificationAction)
Enum: "requested" "authorized" "canceled" "rejected" "inTransit" "delivered" "received" "completed" "active" "approved" "processed" "archived" "deleted" "updated" "ProcessRefund" "ProcessGiftCard" "ProcessExchange" "ProcessWarranty" "ProcessRestock"

Subtype of Notification.

rlRmaId
required
number <double>
correlationId
required
string
Array of objects (ExternalProcessingActionError)
object (EcommerceExchangeTotalsResponse)

Responses

Request samples

Content type
application/json
{
  • "action": "requested",
  • "rlRmaId": 0,
  • "correlationId": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "received": true,
  • "errors": [
    ]
}

GiftCard

Acknowledge Giftcard Success

After a PublicApplication has successfully processed a giftCard request, the PublicApplication will acknowledge that the giftCard was successful through this endpoint.

path Parameters
rlRmaId
required
integer <int32>

RMA identifier

Request Body schema: application/json
action
required
string (WebHookNotificationAction)
Enum: "requested" "authorized" "canceled" "rejected" "inTransit" "delivered" "received" "completed" "active" "approved" "processed" "archived" "deleted" "updated" "ProcessRefund" "ProcessGiftCard" "ProcessExchange" "ProcessWarranty" "ProcessRestock"

Subtype of Notification.

rlRmaId
required
number <double>
correlationId
required
string
Array of objects (ExternalProcessingActionError)
object (GiftCardResponseData)

GiftCardRes