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.

POST/customers

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 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_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_number is 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_name unless foreign.

  • Name
    sdi_code
    Type
    string
    required
    Italian alias: fe_sdi
    Description

    SDI code; 0000000 for 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.Customer
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

POST
/customers
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"
}
POST/customers/{customer_id}/invitations

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 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.

    length ≥ 1, length ≤ 255.

  • Name
    customer_id
    Type
    string
    required
    Description

    Customer id.

Responses

  • 201Invitation sent.CustomerInvitation
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

POST
/customers/{customer_id}/invitations
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_number is 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_name unless foreign.

  • Name
    sdi_code
    Type
    string
    required
    Italian alias: fe_sdi
    Description

    SDI code; 0000000 for 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.

BadRequest

Unauthorized

Forbidden

Conflict

Gone

Unprocessable

TooManyRequests

ServerError

BadGateway

NotFound

Was this page helpful?