CCBill API: Tangibles

Introduction

This document is an Addendum to the CCBill API and discusses Merchant configuration of the CCBill API to implement sales of Subscription Tangibles.

Scope

The CCBill API is considered to be an Advanced Feature of CCBill’s system. This document assumes the following:

The user has already enabled the CCBill API.
The user possesses intermediate to advanced programming skills.
The user’s company sells single and/or recurring shipments and has completed all required processes to enable said feature on the account and/or subaccount.
The user has access to the supported shippers; UPS, USPS, and/or FedEx.

Overview

Three actions have been added to the CCBill API, createFulfillment, updateFulfillment, and getFulfillmentStatus. These actions allow for shipment information to be inserted and maintained in our system.

Action Structure

Each action made through the CCBill API to the CCBill system must include the standard applicable CCBill API parameters (clientAccnum, clientSubacc, usingSubacc, username, password, returnXML- not all are required. See the CCBill API Guide for more information about the CCBill API basic structure.

Actions

The Actions and their respective parameters are listed in this section. CCBill’s system will send a response to the action; possible responses are defined in the Response section later in this document.

createFulfillment

The createFulfillment action allows you to insert shipment information into our system. The action consists of the following required parameters:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shippingCompany	Identifies the name of the company performing the physical shipment.	Allowed parameters are: 1. UPS (United Parcel Service) 2. USPS (United States Postal Service) 3. FedEx (Formerly Federal Express) These parameters are case sensitive.
trackingId	Identifies the tracking number for the company performing the physical shipment.	For UPS: 4-20 character alphanumeric. For USPS* (Mail Class or Service (With Sample Label ID Number)): Express Mail® EA 000 000 000 US* Express Mail International® EC 000 000 000 US* Priority Mail International® CP 000 000 000 US* Global Express Guaranteed® 82 000 000 00* Registered Mail RA 000 000 000 US* Delivery Confirmation 0000 0000 0000 0000 0000 00* For FedEx: *12 digit numeric

createFulfillment Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=createFulfillment&transactionId=12345678987654321&shippingCompany=FedEx&trackingId=123456789987

updateFulfillment

The updateFulfillment action allows you to update existing shipper and/or tracking number for a transactionId. Any data you send using this action will replace the previously sent shippingCompany and trackingId parameters from the previous createFulfillment or updateFulfillment actions and replace it with the data being sent.

The following parameters are required for an updateFulfillment action:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentId	Generated by CCBill and sent with the original createFulfillment response and used to identify the shipment.	Numerical characters of varying length, never more than 20 characters.
shippingCompany	Identifies the name of the company performing the physical shipment.	Allowed parameters are: 1. UPS (United Parcel Service) 2. USPS (United States Postal Service) 3. FedEx (Formerly Federal Express) These parameters are case sensitive.
trackingId	Identifies the tracking number for the company performing the physical shipment.	For UPS: 4-20 character alphanumeric. For USPS* (Mail Class or Service (With Sample Label ID Number)): Express Mail® EA 000 000 000 US* Express Mail International® EC 000 000 000 US* Priority Mail International® CP 000 000 000 US* Global Express Guaranteed® 82 000 000 00* Registered Mail RA 000 000 000 US* Delivery Confirmation 0000 0000 0000 0000 0000 00* For FedEx: *12 digit numeric

updateFulfillment Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=updateFulfillment&transactionId=12345678987654321&shipmentId=123456&shippingCompany=FedEx&trackingId=123456789887

getFulfillmentStatus

The getFulfillmentStatus action allows you to query the CCBill system for previously stored fulfillment data for a transaction.

The getFulfillmentStatus action uses the following parameters:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentId	Generated by CCBill and sent with the original createFulfillment response and used to identify the shipment.	Optional parameter. Numerical characters of varying length, never more than 20 characters.

getFulfillmentStatus Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=getFulfillmentStatus&transactionId=12345678987654321&shipmentId=123456

Response

Success

Successful responses will be returned with some or all of the following parameters:

Response	Purpose	Data
trackingId	Identifies the tracking number for the company performing the physical shipment.	For UPS: 4-20 character alphanumeric. For USPS* (Mail Class or Service (With Sample Label ID Number)): Express Mail® EA 000 000 000 US* Express Mail International® EC 000 000 000 US* Priority Mail International® CP 000 000 000 US* Global Express Guaranteed® 82 000 000 00* Registered Mail RA 000 000 000 US* Delivery Confirmation 0000 0000 0000 0000 0000 00* For FedEx: *12 digit numeric
shipmentId	Generated by CCBill and sent with the original createFulfillment response and used to identify the shipment.	Optional parameter. Numerical characters of varying length, never more than 20 characters.
creationDate	The date and time that the record was created.	2010-06-01T15:27:11.529-07:00 YYYY-MM-DDTHH:mm:ss.lllooo:00 YYYY is the 4-digit year$$$MM is the 2-digit month DD is the 2-digit day HH is the 2-digit hour mm is the 2-digit minute ss is the 2-digit second lll is the 3 digit milliseconds ooo:00 is the GMT offset (IE -07:00 is GMT-7)
nextCheckTime	The next time the CCBill system will check the shipment status.	2010-06-01T15:27:11.529-07:00 YYYY-MM-DDTHH:mm:ss.lllooo:00 YYYY is the 4-digit year$$$MM is the 2-digit month DD is the 2-digit day HH is the 2-digit hour mm is the 2-digit minute ss is the 2-digit second lll is the 3 digit milliseconds ooo:00 is the GMT offset (IE -07:00 is GMT-7)
prevShipmentId	Allows clients to retrieve previously stored shipment information for a transaction; always the most recent.	Numerical characters of varying length, never more than 20 characters.
checkStatusURL	The URL that CCBill uses to check the status of the shipment.	http://www.shipperurl.com/
ccbillShipmentStatus	The status code that CCBill uses for shipments.	See section: Status Codes* later in this document for a list of CCBill Status Codes and their meanings.
shippingCompany	Identifies the name of the company performing the physical shipment.	Allowed parameters are: *UPS (United Parcel Service)

Success Response Sample

Comma Delimited Response

"trackingId","shipmentId","creationDate","shipperStatus","nextCheckTime","prevShipmentId","checkStatusURL","ccbillShipmentStatus","shippingCompany"
"1","13","2010-06-01T15:27:11.529-07:00","ERROR RESPONSE","2010-06-01T23:27:23.326-07:00","0", "http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1","SHIPPER_ERROR","FedEx"

XML Response

<?xml version='1.0' standalone='yes'?> 
<results>
   <shipmentInfos>
     <name>ShipmentTO</name>
     <ccbillShipmentStatus>SHIPPER_ERROR</ccbillShipmentStatus>
     <checkStatusURL>http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1</checkStatusURL>
     <creationDate>2010-06-01T15:36:05.159-07:00</creationDate>
     <nextCheckTime>2010-06-01T23:36:08.211-07:00</nextCheckTime>
     <prevShipmentId>13</prevShipmentId>
     <shipmentId>14</shipmentId>
     <shipperStatus>ERROR RESPONSE</shipperStatus>
     <shippingCompany>FedEx</shippingCompany>
     <trackingId> EA 000 000 000 US</trackingId>
   </shipmentInfos>
   <transactionInfo>
     <clientAccnum>900000</clientAccnum>
     <clientSubacc>0000</clientSubacc>
     <creationDate>2010-06-01T15:27:10-07:00</creationDate>
     <subscriptionId>910130101000000003</subscriptionId>
     <transactionId>910068201000000000</transactionId>
   </transactionInfo> 
</results>

Status Codes

Code	Description
NO_DATA	The initial status for each Shipment that appears when fulfillment information has not been added or has not been added successfully.
PENDING	Indicates that fulfillment data entered by the client is waiting to be sent to the shipper for its first status check; fulfillment data has been entered but the 8 hour waiting period for the initial shipper check has not yet passed.
SHIPPED	This is the status indicating a Shipment is with the shipper but not yet received by the consumer.
SHIPPER_ERROR	The Shipment company has returned an error similar to “status not available” to our system during the most recent status check.
DELIVERED	The Shipment company has returned a status to us that indicates that the shipment has been delivered to the receiver.
NOT_DELIVERABLE	Indicates that a shipment cannot be delivered to the consumer for some reason, including address errors and refusals.
CLEARED	A CCBill staff member has cleared the status and set it as OK.

Error

Errors can be caused for any number of reasons, the most common being data validation errors. Here is a list of data validation performed by the Subscription Tangibles functions:

The Merchant Account Number, Subaccount Number, Subscription ID, or Transaction ID information is checked for accuracy.
The Tracking ID and Shipper must be present.
The Transaction ID provided belongs to the Merchant’s account (and Subaccount, if applicable).
The Tracking ID provided must match one of the Shipper’s accepted formats (provided above).

An error response will typically contain two parameters:

errorDesc: This is a description of the error your action received from our system.
errorCode: This is the code number that the error is stored under in our system.

All possible errors, along with troubleshooting information, are included in this table:

errorDesc	errorCode	Description
ERROR_SERVICE_ERROR	-200	This is a generic error code and usually indicates that the service is temporarily unavailable.
ERROR_MISSING_PARAM	-201	One of the parameters required for the function was not included in the action. Refer to the chart above for required parameters for the action you are trying to make, and verify that the format for your action is correctly constructed.
ERROR_NO_MATCHING_SHIPMENT	-202	The shipmentId parameter contains unknown/non-matching shipment identification information.
ERROR_INVALID_TRACKING_NUMBER	-203	The trackingId parameter contains invalid information. Check to make sure that the trackingId contains all expected characters, matches the format expected for the shippingCompany parameter (see chart above) and verify the trackingId on the shipment receipt provided by your shipping company.
ERROR_NO_MATCHING_TRANSACTION	-204	The transactionId provided in the action does not match any previously known transactionId for your Account number (and Subaccount number, if applicable). Verify the transactionId and resubmit, if necessary.