Charge customer (or absorb) the cost delta after a re-rate

curl --request POST \
  --url https://api.arcuserp.com/v1/packages/{id}/recharge-label \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "recharge",
  "payment_method_id": "pm_1AbcD2eF3G4HiJkL5mNoPqR6",
  "notes": "Customer requested overnight upgrade for birthday delivery"
}
'

import requests

url = "https://api.arcuserp.com/v1/packages/{id}/recharge-label"

payload = {
    "action": "recharge",
    "payment_method_id": "pm_1AbcD2eF3G4HiJkL5mNoPqR6",
    "notes": "Customer requested overnight upgrade for birthday delivery"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'recharge',
    payment_method_id: 'pm_1AbcD2eF3G4HiJkL5mNoPqR6',
    notes: 'Customer requested overnight upgrade for birthday delivery'
  })
};

fetch('https://api.arcuserp.com/v1/packages/{id}/recharge-label', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/packages/{id}/recharge-label",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'recharge',
    'payment_method_id' => 'pm_1AbcD2eF3G4HiJkL5mNoPqR6',
    'notes' => 'Customer requested overnight upgrade for birthday delivery'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/packages/{id}/recharge-label"

	payload := strings.NewReader("{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/packages/{id}/recharge-label")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/packages/{id}/recharge-label")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "delta": 123,
    "action": "recharge",
    "shipping_total_updated": true,
    "gl_je_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "charge_status": "charged",
    "charge_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "label_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "idempotent": true
  }
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Fulfillment

Charge customer (or absorb) the cost delta after a re-rate

Required API key scope: fulfillment:write

NEW-GAP-RERATE-SHIPPING-CHARGE-DELTA-WORKFLOW (2026-05-16). Reuben verbatim: “customer pays overnight”. Use case: customer originally chose Ground ( $12 carrier cost). Now they want Overnight ($ 45). After the operator re-rates and buys a new label, this endpoint settles the cost delta.

Three actions on the package’s active (non-voided) label:

recharge — update orders.shipping_total to the new carrier cost, post a GL revenue delta (DR AR / CR shipping_income for delta_amount), optionally charge the customer’s saved Stripe card via payment_method_id.
absorb — log the absorbed cost; leave orders.shipping_total and GL unchanged.
manual — flag for offline handling; no GL/total change.

Idempotent: one shipping_delta JE per label, ever. Re-calling with the same label_id returns { idempotent: true } with no side effects.

Soft-fail on Stripe decline: when payment_method_id is supplied and the card declines, the GL delta and shipping_total update have already committed; the response carries charge_status: 'declined' so the caller can offer the customer a hosted-checkout payment link.

Delegates to canonical helper createShippingDeltaCharge in arcus-api-core/utils/shipping-recharge-helpers.mjs.

POST

packages

{id}

recharge-label

Charge customer (or absorb) the cost delta after a re-rate

curl --request POST \
  --url https://api.arcuserp.com/v1/packages/{id}/recharge-label \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "recharge",
  "payment_method_id": "pm_1AbcD2eF3G4HiJkL5mNoPqR6",
  "notes": "Customer requested overnight upgrade for birthday delivery"
}
'

import requests

url = "https://api.arcuserp.com/v1/packages/{id}/recharge-label"

payload = {
    "action": "recharge",
    "payment_method_id": "pm_1AbcD2eF3G4HiJkL5mNoPqR6",
    "notes": "Customer requested overnight upgrade for birthday delivery"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'recharge',
    payment_method_id: 'pm_1AbcD2eF3G4HiJkL5mNoPqR6',
    notes: 'Customer requested overnight upgrade for birthday delivery'
  })
};

fetch('https://api.arcuserp.com/v1/packages/{id}/recharge-label', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/packages/{id}/recharge-label",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'recharge',
    'payment_method_id' => 'pm_1AbcD2eF3G4HiJkL5mNoPqR6',
    'notes' => 'Customer requested overnight upgrade for birthday delivery'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/packages/{id}/recharge-label"

	payload := strings.NewReader("{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/packages/{id}/recharge-label")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/packages/{id}/recharge-label")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"recharge\",\n  \"payment_method_id\": \"pm_1AbcD2eF3G4HiJkL5mNoPqR6\",\n  \"notes\": \"Customer requested overnight upgrade for birthday delivery\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "delta": 123,
    "action": "recharge",
    "shipping_total_updated": true,
    "gl_je_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "charge_status": "charged",
    "charge_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "label_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "idempotent": true
  }
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Authorizations

Authorization

string

header

required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Headers

Idempotency-Key

string

Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.

Maximum string length: 255

Path Parameters

string<uuid>

required

Body

application/json

action

enum<string>

required

What to do with the cost delta. recharge bills the customer (requires payment_method_id for in-API Stripe charge). absorb logs but does not move money. manual flags for offline handling.

Available options:

recharge,

absorb,

manual

label_id

string<uuid>

Optional explicit label id. When omitted, the active (non-voided) label on the package is used.

payment_method_id

string

Saved Stripe payment method to charge for the delta. Only honored when action='recharge' and the carrier cost exceeds what the customer was charged. Soft-fails on decline.

update_order_total

boolean

default:true

When true (default) and action='recharge', updates orders.shipping_total to match the new carrier cost and re-flows totals via recalculateOrderTotals.

notes

string

Optional human note recorded on the activity log entry and (for the recharge branch) on the Stripe charge description.

Response

Delta processed

data

object

Show child attributes

Overview

All Endpoints

Charge customer (or absorb) the cost delta after a re-rate

Authorizations

Headers

Path Parameters

Body

Response