Foundations

Asynchronous Operations

For some endpoints, Rutter support different response_mode parameters. This parameter allows you to specify whether to:

  1. Call the API in a synchronous fashion & wait for the response. This is the default behavior if no response_mode is specified.
  2. Call the API in an asynchronous fashion, receive a response immediately with a URL pointer to the request job, and wait for the result to be updated via the URL.

Using the async response mode is recommended when:

  • You want to make idempotent operations to avoid creating duplicate requests when sending the same payload. You can accomplish this by passing the distinct value through the Idempotency-Key request header.
  • You have specific latency requirements, and do not wish to wait multiple seconds for a response from the Rutter endpoint.
  • You want to make a large set of operations at the same time. This allows Rutter to intelligently avoid rate limit when making many requests to an external platform.

Request: How to include the response_mode parameter

The response_mode parameter will appear in the request body of the API call. The value of the parameter can be either prefer_sync or async.

Example Invoice with a specified `response_mode`
{
  "response_mode": "async", // or "prefer_sync"
  "invoice": {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "customer_id": "00000000-0000-0000-0000-000000000000",
    "due_date": "2023-01-02T02:34:56.000Z",
    "issue_date": "2023-01-02T02:34:56.000Z",
    "currency_code": "USD",
    "line_items": [
      {
        "total_amount": 10,
        "description": "A Rutter Shirt",
        "item": {
          "id": "00000000-0000-0000-0000-000000000000",
          "quantity": 1,
          "unit_amount": 10
        }
      }
    ]
  }
}
Optionally include `Idempotency-Key` in the Request Header
  Content-Type: "application/json"
  Authorization: "Basic 00000"
  User-Agent: "PostmanRuntime/7.32.3"
  Accept: "application/json"
  Cache-Control: "no-cache"
  Postman-Token: "00000000-0000-0000-0000-000000000000"
  Host: "production.rutterapi.com"
  Accept-Encoding: "gzip, deflate, br"
  Connection: "keep-alive"
  Content-Length: "1000"

  Idempotency-Key: "12345678-90ab-cdef-fedc-ba0987654321"

Response Mode: Prefer Sync

If you set response_mode to be prefer_sync, the request will try to return a synchronous response if the entire product is created within 30 seconds. If it takes longer, we will return an async_response object that contains a URL pointer to be used to query the status of the request as it continues to make progress on our server. This async_response object is the same format as if you set response_mode to be async.

Response Mode: Async

If you set response_mode to be async, the request will be run asynchronously and the API will immediately return an async_response. Query the response_url field on async_response for the status of the request.

If an async_response is returned, it has the following properties:

PropertyTypeDescription
idStringA unique UUID string representing the ID of the Async Job.
response_urlStringA link to the Fetch a Job endpoint. By making a GET request to this URL, you can retrieve the status and result of the job.
statusStringThe status of the job. One of the following
  • prequeued
  • pending
  • success
  • failure

We suggest querying the response_url field for the status of the request. The response_url corresponds to the Fetch a Job endpoint, and will return the successful result or errors encountered during the request.

Async Job Webhook

When an Asynchronous Job is successful, we will also send a webhook to your configured webhook URLs.

JSON
{
  "type": "JOB",
  "code": "JOB_COMPLETED",
  "job": {
    "id": "3446b185-117f-46bc-939b-aa53de5c35c1",
    "status": "success",
    "request": {
      "url": "https://production.rutterapi.com/versioned/products",
      "method": "POST",
      "body": {
        // Asynchronous Job Request Body
      }
    },
    "response": {
      "http_status": 200,
      "body": {
        // Asynchronous Job Response Body
      }
    }
  }
}

The AsynchronousJob object

Properties

idstring
statusenum
One ofprequeuedpendingsuccess, or failure.
responseobjectoptional

The response to a request executed as a job

Show response attributes
requestobject

The request that kicked off the job

Show request attributes

Fetch a Job

GET /versioned/jobs/:id
Supported for: All Platforms

Request Parameters

    idstringpath

    The ID of the job.

Response Body

    idstring
    statusenum
    One ofprequeuedpendingsuccess, or failure.
    responseobjectoptional

    The response to a request executed as a job

    Show response attributes
    requestobject

    The request that kicked off the job

    Show request attributes