Developer Partners onboarding

Introduction

This document outlines the process of onboarding Individual Merchants and Known Shippers within the Shipping360 platform. The objective is to provide clear guidance on how developers can integrate and manage their own shipping operations or those of their partners.

Shipping360 offers a comprehensive platform that supports both Individual Merchants, who manage their shipping independently, and Known Shippers, who rely entirely on the developer for their shipping operations.

Developer

A Developer is the user who integrates the Shipping360 platform's services into their own or their client's systems. Developers use the platform's APIs to automate shipping tasks, such as creating shipments, generating shipping labels, calculating shipping rates, and tracking shipments.

They also manage partner accounts (e.g., Individual Merchants or Known Shippers), allowing these partners to benefit from the platform's shipping capabilities without needing to handle the technical setup themselves.

Developer Account

A Developer Account is required to use the Shipping360 platform's APIs and its features. This account gives developers access to:

  1. API Keys: These keys are necessary for authenticating and making requests to Shipping360's APIs.
  2. Sandbox Environment: A testing environment where developers can try out features and build solutions before moving to real operations.
  3. Production Environment: The live environment where developers manage real shipments, print shipping labels, and handle transactions for their partners.
  4. API Documentation: Developers can access the API 360 developer documentation.
  5. Partner Management: Developers can manage multiple partners (both Developer Partners and Known Shippers) under their account.

Partner Account

A Partner Account is an account created for Developer Partners (Individual Merchants or Known Shippers) within the API 360 platform. The type of partner determines how much control they have over their shipping operations:

Individual Merchant

An Individual Merchant is a business or entity that can manage their own Carriers and Payment accounts using the API 360 platform. They are onboarded by the developer but can independently perform tasks such as managing their carrier accounts, payment accounts, and viewing their shipping history.

Known Shipper

A Known Shipper is a business that completely relies on the developer to manage its shipping operations and interactions with the API 360 platform. The developer handles all shipping tasks on behalf of the known shipper, such as printing labels, calculating rates, and tracking shipments.

Onboarding Developer Partners: Individual Merchant

Individual merchants can be of two types:

  1. An existing SP360 customer (Developer or Merchant) who is already registered with PB.
  2. A new user who does not have an SP360 subscription or is not registered with PB.

Developers can onboard an individual merchant in two ways: through the Developer Dashboard or by using the onboard invitation API.

Invite a New User as an Individual Merchant through the Dashboard

The developer needs to access their PitneyShip Developer Dashboard:

  1. In the top navigation, go to the API tab.
  2. From the dropdown, select API Keys and Developer Documentation.
Developer Dashboard
  1. The 360 API Developer Dashboard will open.
  2. In the portal, navigate to the Merchant tab and select +Invite Merchant.
  3. In the Invite Merchant form, enter the merchant's email address and set the expiration date for the invitation.
  4. Click Send Invitation.
Invite Merchant vis UI
  1. The invited merchant will appear in the Merchants list with the status Invited.
  2. Once the merchant accepts the invitation, their status will change to Active.

    Merchant in Invited States

Merchant Invited

Merchant in Active States

Merchant Accepted invitation
  1. The individual merchant can now log in to the Pitney Bowes Cloud and set up their Cost Accounts and Carrier.
Individual Merchant Dashboard

Invite existing customer as an Individual Merchant through Dashboard

To invite an existing customer as a merchant, access the 360 API Developer Dashboard by navigating to the API tab and selecting API Keys and Developer Documentation.

  1. In the Merchant tab, click +Invite Merchant, enter the merchant's (existing customer) email and expiration date, then click Send Invitation.
  2. An acceptance link will be generated for the customer.
Invitation link for existing customer
  1. Open the link and accept the onboarding invitation by clicking on the Accept button.
Acceptance link for existing customer
  1. The customer will receive a successful registration acknowledgment.
Invitation Acceptance Confirmation

Invite new user as an Individual Merchant through onboard invitation API

To invite an individual merchant to the API 360 platform using the onboard invitation API, follow the process below:

  1. Send the API Request:
    To invite an individual merchant, use the following API request format:

API Request Example:

Copy
Copied
curl --location 'https://api-sandbox.sendpro360.pitneybowes.com/developerprofile/api/v1/invitation' \
--header 'Authorization: Bearer XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "partnerEmailId": "nas_merchant@yopmail.com",
    "expirationDays": 7
}'

Requirement:

  • Email Address: The email ID of the merchant. Only one invitation can be generated per email address.
  • Request Expiration Days: Specify the number of days the invitation will remain valid. Once the invitation expires, a new invitation request can be generated for the same email address.

    This request generates an onboarding invitation for the individual merchant, allowing them to set up their account on the Shipping360 platform within the specified expiration period.

  1. Receive the Response:
    The response will contain the invitationId, the invitation status, and a link for the merchant to complete their onboarding.

    API Response Example:

Copy
Copied
{
    "invitationId": "G3Qeb9RPr5r793M",
    "developerId": "sacd74e",
    "email": "ns_merchant@yopmail.com",
    "status": "Invited",
    "invitationType": "ONBOARD_REQUEST",
    "createdBy": "0oa273lb1u122pDkP0h8",
    "ProvisioningRequestID": "",
    "ConsumerType": 0,
    "archived": false,
    "link": "https://api-sandbox.sendpro360.pitneybowes.com/merchant-signup?invitationId=G3Qeb9RPr5r793M&invitationType=ONBOARD_REQUEST",
    "insertTimestamp": "2024-09-24T11:17:59.685574367Z",
    "updateTimestamp": "2024-09-24T11:17:59.685575029Z",
    "expirationDate": "2024-10-04T11:17:59.676092541Z"
}
  1. Merchant Receives Invitation:
    The merchant will receive an email with a link to onboard and sign up through the provided merchant-signup URL.
  2. Monitor Status:
    Initially, the merchant's status will be marked as Invited. Once they accept the invitation, their status will change to Active.

Onboard a Known Shipper through Shipper Registration API

Developers can manage funds on behalf of Known Shipper merchants. Registering a merchant as a Known Shipper provides them with a unique Shipper ID.

To onboard a Known Shipper to the Shipping360 platform using the Shipper Registration API, follow the process below:

  1. Send the API Request:
    To onboard a Known Shipper, use the following API request format:

API Request Example:

Copy
Copied
curl --location 'https://api-sandbox.sendpro360.pitneybowes.com/shipping/api/v1/shippers/registration' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXX\
--data-raw '{
    "addressLine1": "address",
    "addressLine2": "",
    "addressLine3": "",
    "cityTown": " Austin ",
    "stateProvince": "TX",
    "postalCode": "733010000",
    "countryCode": "US",
    "name": "John Doe",
    "company": "PB",
    "phone": "5124567800",
    "carrierAccountId": "581wZxpaQeY",
    "email": "testmail@yopmail.com"
}'

Requirement:

  • Email Address: The email ID of the merchant you want to register as a Known Shipper.
  • Carrier Account ID: The unique identifier to use when the merchant performs an operation that uses this carrier account. Obtain it using the Get Carrier Accounts API.
  • Address: The merchant must have a physical U.S. address to obtain a Shipping ID. P.O. Boxes cannot be used as addresses.
  1. Receive the Response:
    The response will contain the ShipperID and the state of the registered merchant as New.

API Response Example:

Copy
Copied
{
    "shipperID": "2000083558",
    "addressLine1": "address",
    "addressLine2": "",
    "addressLine3": "",
    "cityTown": "Austin",
    "stateProvince": "TX",
    "postalCode": "733010000",
    "countryCode": "US",
    "name": "   John Doe",
    "company": "PB",
    "phone": "5124567800",
    "carrierAccountId": "581wZxpaQeY",
    "email": "testmail@yopmail.com",
    "status": "New"
}