Buy a label

POST

/shipments/{id}/buy

curl --request POST \
  --url https://shipjay.com/api/v1/shipments/example/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "rate_id": "example" }'

Spends wallet money on the chosen rate. Requires an Idempotency-Key header: repeating the request with the same key never buys twice. Subject to the key’s per purchase and daily spending limits, the organization’s daily limit and its wallet balance.

Authorizations

• bearerAuth
  shipments:buy

Parameters

Path Parameters

id

required

string

Header Parameters

Idempotency-Key

required

string

>= 8 characters <= 200 characters

A unique value (8 to 200 characters) for this operation. Repeating the request with the same key returns the first result.

Request Body^required

Media typeapplication/json

object

rate_id

required

string

>= 1 characters <= 100 characters

Example ^generated

{
  "rate_id": "example"
}

Responses

200

Success.

Media typeapplication/json

object

shipment_id

required

string

status

required

string

Allowed values: purchased purchasing

tracking_code

required

string | null

balance_after_cents

required

number | null

duplicate

required

boolean

Example

{
  "status": "purchased"
}

401

Missing or invalid API key.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation unauthenticated forbidden not_found conflict insufficient_funds org_suspended spend_limit rate_limited maintenance not_configured upstream internal

message

required

string

details

object

key

additional properties

any

request_id

required

string

Example

{
  "error": {
    "code": "validation"
  }
}

403

The key lacks the required permission, or the account is suspended.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation unauthenticated forbidden not_found conflict insufficient_funds org_suspended spend_limit rate_limited maintenance not_configured upstream internal

message

required

string

details

object

key

additional properties

any

request_id

required

string

Example

{
  "error": {
    "code": "validation"
  }
}

404

The resource does not exist.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation unauthenticated forbidden not_found conflict insufficient_funds org_suspended spend_limit rate_limited maintenance not_configured upstream internal

message

required

string

details

object

key

additional properties

any

request_id

required

string

Example

{
  "error": {
    "code": "validation"
  }
}

422

The request is not valid. error.details.issues lists the problems.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation unauthenticated forbidden not_found conflict insufficient_funds org_suspended spend_limit rate_limited maintenance not_configured upstream internal

message

required

string

details

object

key

additional properties

any

request_id

required

string

Example

{
  "error": {
    "code": "validation"
  }
}

429

Too many requests. Wait Retry-After seconds.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation unauthenticated forbidden not_found conflict insufficient_funds org_suspended spend_limit rate_limited maintenance not_configured upstream internal

message

required

string

details

object

key

additional properties

any

request_id

required

string

Example

{
  "error": {
    "code": "validation"
  }
}