Customers
Create customers in your reseller network. The customer receives an email invitation and chooses their own password: no password ever travels through the API. Your account must be enabled for the customer network; other accounts get 403 FEATURE_NOT_ENABLED.
Create a customer in your network
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Only for accounts enabled for the customer network. Other accounts get 403 FEATURE_NOT_ENABLED.
Creates a user in your reseller network and returns its id, to use as customer_id elsewhere. No password is ever sent or returned. The customer is created in the legacy system, then the identity provider sends the invitation email and hosts the page where the customer chooses a password. The invitation is sent right away, in the Accept-Language language, and the link expires after 7 days (proposed). If the invitation cannot be sent the customer is still created and invitation.status is FAILED: call POST /customers/{customer_id}/invitations. The login name is the email. Only available to accounts with the network function (otherwise 403 FEATURE_NOT_ENABLED). First name, last name and email are normalised by the shared rules before they are stored.
Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
Idempotency-Key- Type
- string
- required
- Description
Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with
Idempotent-Replayed: true; same key with a different body is 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_KEY_REQUIRED.length ≥ 1, length ≤ 255.
Request body CustomerCreate
- Name
last_name- Type
- string
- required
- Italian alias:
cognome - Description
Last name. Normalised by the shared name rules.
- Name
first_name- Type
- string
- required
- Italian alias:
nome - Description
First name. Normalised by the shared name rules.
- Name
address- Type
- string
- required
- Italian alias:
indirizzo - Description
Address.
- Name
postal_code- Type
- string
- required
- Italian alias:
cap - Description
Postal code.
- Name
city- Type
- string
- required
- Italian alias:
localita - Description
City.
- Name
province- Type
- string
- required
- Italian alias:
provincia - Description
Province,
--for foreign customers.
- Name
country_code- Type
- string
- required
- Italian alias:
nazione - Description
ISO 3166-1 alpha-2.
- Name
email- Type
- string (email)
- required
- Italian alias:
email - Description
Email, trimmed and lower-cased.
- Name
phone- Type
- string
- Italian alias:
telefono - Description
Phone.
- Name
mobile- Type
- string
- Italian alias:
cellulare - Description
Mobile.
- Name
company_name- Type
- string
- Italian alias:
ragionesociale - Description
Company name; if set,
vat_numberis required.
- Name
tax_code- Type
- string
- required
- Italian alias:
codicefiscale - Description
Tax code.
- Name
vat_number- Type
- string
- Italian alias:
partitaiva - Description
VAT number.
- Name
pec_email- Type
- string
- Italian alias:
fe_pec - Description
Certified email (PEC); required with
company_nameunless foreign.
- Name
sdi_code- Type
- string
- required
- Italian alias:
fe_sdi - Description
SDI code;
0000000for private individuals.
- Name
bank_name- Type
- string · nullable
- Italian alias:
banca - Description
Bank.
- Name
iban- Type
- string · nullable
- Italian alias:
iban - Description
IBAN, required for cash-on-delivery remittances.
- Name
account_holder- Type
- string · nullable
- Italian alias:
intestazioneconto - Description
Exact account holder name.
Responses
201Customer created, invitation sent.Customer400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error409State conflict. Codes:OFFER_ALREADY_ORDERED,CUSTOMER_ALREADY_EXISTS(email or tax code already registered),INVITATION_ALREADY_ACCEPTED,IDEMPOTENCY_KEY_IN_USE.Error410Version retired. CodeVERSION_RETIRED.Error422The request is well formed but a business rule refuses it. Codes:INSUFFICIENT_CREDIT,SERVICE_NOT_AVAILABLE,CARRIER_NOT_AVAILABLE,IDEMPOTENCY_KEY_REUSED, ...Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 201
{
"id": "3723",
"first_name": "Test",
"last_name": "Tester",
"email": "customer@example.com",
"company_name": null,
"invitation": {
"status": "SENT",
"sent_at": "2026-12-09T09:31:59+00:00",
"expires_at": "2026-12-16T09:31:59+00:00"
},
"created_at": "2026-12-09T09:31:59+00:00"
}Send a customer invitation again
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Only for accounts enabled for the customer network. Other accounts get 403 FEATURE_NOT_ENABLED.
Asks the identity provider to send a new invitation email to a customer who has not chosen a password yet, for example after invitation.status was FAILED or EXPIRED. The previous link stops working. Allowed once per minute. A customer who already accepted gets 409 INVITATION_ALREADY_ACCEPTED; an earlier send less than a minute ago gets 429 RATE_LIMIT_EXCEEDED. NEW capability: the legacy API handed over a password instead.
Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
Idempotency-Key- Type
- string
- required
- Description
Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with
Idempotent-Replayed: true; same key with a different body is 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_KEY_REQUIRED.length ≥ 1, length ≤ 255.
- Name
customer_id- Type
- string
- required
- Description
Customer id.
Responses
201Invitation sent.CustomerInvitation401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error409State conflict. Codes:OFFER_ALREADY_ORDERED,CUSTOMER_ALREADY_EXISTS(email or tax code already registered),INVITATION_ALREADY_ACCEPTED,IDEMPOTENCY_KEY_IN_USE.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 201
{
"status": "SENT",
"sent_at": "2026-12-10T08:00:00+00:00",
"expires_at": "2026-12-17T08:00:00+00:00"
}Models
Objects used by the requests and responses on this page.
CustomerCreate
There is no password and no username: the customer logs in with the email and chooses a password from the invitation link.
- Name
last_name- Type
- string
- required
- Italian alias:
cognome - Description
Last name. Normalised by the shared name rules.
- Name
first_name- Type
- string
- required
- Italian alias:
nome - Description
First name. Normalised by the shared name rules.
- Name
address- Type
- string
- required
- Italian alias:
indirizzo - Description
Address.
- Name
postal_code- Type
- string
- required
- Italian alias:
cap - Description
Postal code.
- Name
city- Type
- string
- required
- Italian alias:
localita - Description
City.
- Name
province- Type
- string
- required
- Italian alias:
provincia - Description
Province,
--for foreign customers.
- Name
country_code- Type
- string
- required
- Italian alias:
nazione - Description
ISO 3166-1 alpha-2.
- Name
email- Type
- string (email)
- required
- Italian alias:
email - Description
Email, trimmed and lower-cased.
- Name
phone- Type
- string
- Italian alias:
telefono - Description
Phone.
- Name
mobile- Type
- string
- Italian alias:
cellulare - Description
Mobile.
- Name
company_name- Type
- string
- Italian alias:
ragionesociale - Description
Company name; if set,
vat_numberis required.
- Name
tax_code- Type
- string
- required
- Italian alias:
codicefiscale - Description
Tax code.
- Name
vat_number- Type
- string
- Italian alias:
partitaiva - Description
VAT number.
- Name
pec_email- Type
- string
- Italian alias:
fe_pec - Description
Certified email (PEC); required with
company_nameunless foreign.
- Name
sdi_code- Type
- string
- required
- Italian alias:
fe_sdi - Description
SDI code;
0000000for private individuals.
- Name
bank_name- Type
- string · nullable
- Italian alias:
banca - Description
Bank.
- Name
iban- Type
- string · nullable
- Italian alias:
iban - Description
IBAN, required for cash-on-delivery remittances.
- Name
account_holder- Type
- string · nullable
- Italian alias:
intestazioneconto - Description
Exact account holder name.
ParceLabsVersion
CorrelationId
KeyLocale
Location
Postal location used to price a shipment.
- Name
postal_code- Type
- string
- required
- Italian alias:
cap - Description
Postal code.
- Name
city- Type
- string
- required
- Italian alias:
localita - Description
City or town.
- Name
province- Type
- string
- Italian alias:
provincia - Description
Italian province code. Use
--for foreign addresses.
- Name
state_code- Type
- string
- Italian alias:
codice_stato - Description
State or province code. Required for US and CA destinations, otherwise omit.
- Name
country_code- Type
- string
- required
- Italian alias:
nazione - Description
ISO 3166-1 alpha-2 country code.
IdempotentReplayed
Customer
- Name
id- Type
- string
- required
- Italian alias:
id_dva - Description
Customer id to use as
customer_id.
- Name
first_name- Type
- string
- Italian alias:
nome - Description
First name.
- Name
last_name- Type
- string
- Italian alias:
cognome - Description
Last name.
- Name
email- Type
- string
- Italian alias:
email - Description
Email.
- Name
company_name- Type
- string · nullable
- Italian alias:
ragionesociale - Description
Company.
- Name
invitation- Type
- CustomerInvitation
- required
- Italian alias:
invito - Description
State of the invitation email.
- Name
created_at- Type
- string (date-time)
- required
- Italian alias:
timestamp - Description
Creation time.
CustomerInvitation
- Name
status- Type
- string
- required
- Italian alias:
stato - Description
SENT: email sent, link valid.FAILED: the identity provider could not send the email, send it again.ACCEPTED: the customer chose a password.EXPIRED: the link expired, send it again.Allowed values:
SENT,FAILED,ACCEPTED,EXPIRED.
- Name
sent_at- Type
- string (date-time) · nullable
- Italian alias:
inviato_il - Description
When the last invitation was sent.
- Name
expires_at- Type
- string (date-time) · nullable
- Italian alias:
scade_il - Description
When the link stops working.