Foundations

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.

{
  "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
        }
      }
    ]
  }
}

  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:

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.

{
  "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
      }
    }
  }
}