API reference

Shipping Rates

Shipping rates describe the price of shipping presented to your customers and applied to a purchase. For more information, see Charge for shipping.

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a shipping rate

POST/v1/shipping_rates

Creates a new shipping rate object.

Body parameters

  • display_namestringRequired

    The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.

  • delivery_estimateobject

    The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.

    Show 2 child parameters
    • maximumobject
      Show 2 child parameters
      • unitstringRequired
        Possible values
        • business_day
        • day
        • hour
        • month
        • week
      • valueintegerRequired
    • minimumobject
      Show 2 child parameters
      • unitstringRequired
        Possible values
        • business_day
        • day
        • hour
        • month
        • week
      • valueintegerRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • fixed_amountobject

    Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

    Show 3 child parameters
    • amountintegerRequired
    • currencystringRequired
    • currency_optionsobject
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • tax_behaviorstring

    Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

    Possible values
    • exclusive
    • inclusive
    • unspecified
  • tax_codestring

    A tax code ID. The Shipping tax code is txcd_92010001.

  • typestring

    The type of calculation to use on the shipping rate.

    Possible values
    • fixed_amount

Returns

The shipping_rate object.

POST /v1/shipping_rates
curl https://api.knoxapi.com/v1/shipping_rates \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "display_name=Ground shipping"
Response
{
  "active": true,
  "created": 1234567890,
  "delivery_estimate": {
    "maximum": {
      "unit": "month",
      "value": 111972721
    },
    "minimum": {
      "unit": "month",
      "value": 111972721
    }
  },
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "id": "shr_1Pgc7AB7WZ01zgkWVPt4WhMx",
  "livemode": false,
  "metadata": {},
  "object": "shipping_rate",
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}

List all shipping rates

GET/v1/shipping_rates

Returns a list of your shipping rates.

Query parameters

  • activeboolean

    Only return shipping rates that are active or inactive.

  • createdobject | integer

    A filter on the list, based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • currencystring

    Only return shipping rates for the given currency.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of shipping_rate objects.

GET /v1/shipping_rates
curl -G https://api.knoxapi.com/v1/shipping_rates \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/shipping_rates",
  "has_more": false,
  "data": [
    {
      "active": true,
      "created": 1234567890,
      "delivery_estimate": {
        "maximum": {
          "unit": "month",
          "value": 111972721
        },
        "minimum": {
          "unit": "month",
          "value": 111972721
        }
      },
      "display_name": "Ground shipping",
      "fixed_amount": {
        "amount": 500,
        "currency": "usd"
      },
      "id": "shr_1Pgc7AB7WZ01zgkWVPt4WhMx",
      "livemode": false,
      "metadata": {},
      "object": "shipping_rate",
      "tax_behavior": "unspecified",
      "tax_code": null,
      "type": "fixed_amount"
    }
  ]
}

Update a shipping rate

POST/v1/shipping_rates/{shipping_rate_token}

Updates an existing shipping rate object.

Path parameters

  • shipping_rate_tokenstringRequired

Body parameters

  • activeboolean

    Whether the shipping rate can be used for new purchases. Defaults to true.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • fixed_amountobject

    Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

    Show 1 child parameter
    • currency_optionsobject
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • tax_behaviorstring

    Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

    Possible values
    • exclusive
    • inclusive
    • unspecified

Returns

The shipping_rate object.

POST /v1/shipping_rates/{shipping_rate_token}
curl https://api.knoxapi.com/v1/shipping_rates/shipping_rate_token_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "active": true,
  "created": 1234567890,
  "delivery_estimate": {
    "maximum": {
      "unit": "month",
      "value": 111972721
    },
    "minimum": {
      "unit": "month",
      "value": 111972721
    }
  },
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "id": "shr_1Pgc7AB7WZ01zgkWVPt4WhMx",
  "livemode": false,
  "metadata": {},
  "object": "shipping_rate",
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}

Retrieve a shipping rate

GET/v1/shipping_rates/{shipping_rate_token}

Returns the shipping rate object with the given ID.

Path parameters

  • shipping_rate_tokenstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The shipping_rate object.

GET /v1/shipping_rates/{shipping_rate_token}
curl https://api.knoxapi.com/v1/shipping_rates/shipping_rate_token_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active": true,
  "created": 1234567890,
  "delivery_estimate": {
    "maximum": {
      "unit": "month",
      "value": 111972721
    },
    "minimum": {
      "unit": "month",
      "value": 111972721
    }
  },
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "id": "shr_1Pgc7AB7WZ01zgkWVPt4WhMx",
  "livemode": false,
  "metadata": {},
  "object": "shipping_rate",
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.