Shipments Endpoint | Ticket Evolution API Docs

Shipments can belong to both orders and purchase orders. They contain "items" which are the ticket groups included in that shipment.

Orders and Purchase orders can have multiple shipments.

Shipment states for any shipment of type "fedex" will automatically be updated during the entire delivery process.

The API is currently integrated with FedEx. Additional delivery services will be added soon.

Each shipment has a state which can be:
"pending" - the shipment starts off in the pending state.
"in_transit" - the shipment has been picked up and is on it's way to the customer.
"delivered" - the shipment has been delivered
"returned" - the shipment has been returned to the sender and a new shipment will need to be created to deliver the tickets.
"exception" - there was an exception during attempted delivery and another attempt will need to be made. For instance the customer was not available to receive the shipment.

List
GET /shipments

Sample Code

/**
 * Setup configuration
 */
$cfg['params']['apiToken'] = (string) '111222333444555666777888999';
$cfg['params']['secretKey'] = (string) 'aaabbbcccdddeeefffggghhhiiijjjkkk';
$cfg['params']['apiVersion'] = (string) '9';
$cfg['params']['buyerId'] = '666';
$cfg['params']['baseUri'] = (string) 'https://api.ticketevolution.com';

$config = new Zend_Config($cfg);

/**
 * Finished setting up configuration.
 * Initialize a TicketEvolution_Webservice object.
 */
$tevo = new TicketEvolution_Webservice($config->params);

/**
 * Below here is where all the method-specific stuff is.
 */
$options = array(
    'page' => 1,
    'per_page' => 10,
    'state' => 'in_transit',
);

$results = $tevo->listShipments($options);

Sample Response

{
                "shipments" => [
                [0] {
                                    "type" => "FedEx",
                            "phone_number" => nil,
                              "updated_at" => "2012-07-12T01:50:06Z",
                            "ship_to_name" => nil,
                    "service_type_display" => nil,
                         "tracking_number" => "794968599530",
                                 "airbill" => "http://s3.amazonaws.com/media.sandbox.ticketevolution.com/shipments/airbills/1/original.pdf?1310423341",
                    "ship_to_company_name" => nil,
                                   "state" => "pending",
                                    "name" => nil,
                          "signature_type" => nil,
                                 "address" => nil,
                                     "url" => "/shipments/1",
                                   "items" => [
                        [0] {
                                "quantity" => 1,
                            "ticket_group" => {
                                           "row" => "8",
                                       "section" => "304",
                                      "quantity" => nil,
                                "external_notes" => "View Reserve Right Field",
                                         "event" => {
                                    "occurs_at" => "2011-09-27T19:15:00Z",
                                        "venue" => {
                                           "name" => "AT&T Park",
                                        "address" => nil,
                                             "id" => "1172"
                                    },
                                         "name" => "San Francisco Giants vs. Colorado Rockies",
                                          "url" => "/events/58039",
                                           "id" => "58039"
                                },
                                     "office_id" => 141,
                                         "seats" => [],
                                     "remote_id" => "10266",
                                           "url" => "/ticket_groups/4099982",
                                            "id" => "4099982"
                            },
                                      "id" => "83"
                        }
                    ],
                                      "id" => "1",
                                   "order" => {
                         "id" => "83",
                        "url" => "/orders/83"
                    },
                            "service_type" => nil
                }
            ],
            "total_entries" => 898,
             "current_page" => 1,
                 "per_page" => 1
}

Parameters

Name	Value	Description
state		The state of the shipment.
client_order_id		Pass an ID of an client order to request shipments that belong to that order.
partner_order_id		Pass an ID of a partner order to request shipments that belong to that order.
order_id		Pass an ID of a brokerage order to request shipments that belong to that order.
tracking_number		The tracking number of the shipment
shipment_type		The type of shipment can include FedEx, Will Call, UPS, or Courier
updated_at		An ISO 8601 date time when the performer was last updated. Use in combination with the conditionals like `.gte` to get updated since.
page		Number of pages that you want to return
per_page		Number of results returned per page

Show
GET /shipments/:shipment_id

Sample Code

/**
 * Setup configuration
 */
$cfg['params']['apiToken'] = (string) '111222333444555666777888999';
$cfg['params']['secretKey'] = (string) 'aaabbbcccdddeeefffggghhhiiijjjkkk';
$cfg['params']['apiVersion'] = (string) '9';
$cfg['params']['buyerId'] = '666';
$cfg['params']['baseUri'] = (string) 'https://api.ticketevolution.com';

$config = new Zend_Config($cfg);

/**
 * Finished setting up configuration.
 * Initialize a TicketEvolution_Webservice object.
 */
$tevo = new TicketEvolution_Webservice($config->params);

/**
 * Below here is where all the method-specific stuff is.
 */
$results = $tevo->showShipment(83);

Sample Response

{
                            "type" => "FedEx",
                    "phone_number" => nil,
                      "updated_at" => "2012-07-12T01:50:08Z",
                    "ship_to_name" => nil,
            "service_type_display" => nil,
                 "tracking_number" => "797323274330",
                         "airbill" => "http://s3.amazonaws.com/media.sandbox.ticketevolution.com/shipments/airbills/83/original.pdf?1311182298",
            "ship_to_company_name" => nil,
                           "state" => "pending",
                            "name" => nil,
                  "signature_type" => nil,
                         "address" => nil,
                             "url" => "/shipments/83",
                           "items" => [
                [0] {
                        "quantity" => 2,
                    "ticket_group" => {
                                   "row" => "J",
                               "section" => "149",
                              "quantity" => nil,
                        "external_notes" => nil,
                                 "event" => {
                            "occurs_at" => "2011-09-10T16:10:00Z",
                                "venue" => {
                                   "name" => "Comerica Park",
                                "address" => nil,
                                     "id" => "1782"
                            },
                                 "name" => "Detroit Tigers vs. Minnesota Twins",
                                  "url" => "/events/57920",
                                   "id" => "57920"
                        },
                             "office_id" => 27,
                                 "seats" => [],
                             "remote_id" => "48430",
                                   "url" => "/ticket_groups/6884656",
                                    "id" => "6884656"
                    },
                              "id" => "168"
                }
            ],
                              "id" => "83",
                           "order" => {
                 "id" => "168",
                "url" => "/orders/168"
            },
                    "service_type" => nil
}

Parameters

Name	Value	Description
shipment_id		ID of the shipment

Create
POST /shipments

To configure these options log into the Ticket Evolution Settings App and then Checkout -> Shipping.

Sample Code

Sample Request Body

{
   "shipments":[
      {
         "service_type":"LEAST_EXPENSIVE",
         "items":[
            {
               "id":"253"
            }
         ],
         "airbill":"",
         "order_id":"253",
         "tracking_number":"798766684568",
         "type":"FedEx",
         "phone_number_attributes":{
            "country_code":null,
            "extension":null,
            "number":"123-243-6697",
            "label":"work"
         },
         "address_attributes":{
            "country_code":"US",
            "street_address":"123 Fake St.",
            "locality":"New York",
            "postal_code":"10001-0000",
            "region":"NY"
         },
         "ship_to_name":"John Doe"
      }
   ]
}

Sample Response

{
   "shipments":[
      {
         "order":{
            "url":"/orders/253",
            "id":"253"
         },
         "state":"pending",
         "type":"FedEx",
         "address":{
            "street_address":"123 Fake St.",
            "latitude":null,
            "postal_code":"10001-0000",
            "extended_address":null,
            "longitude":null,
            "country_code":"US",
            "locality":"New York",
            "label":null,
            "region":"NY"
         },
         "url":"/shipments/8051",
         "updated_at":"2012-04-24T20:41:09Z",
         "service_type":null,
         "service_type_display":null,
         "airbill":"http://media.staging.ticketevolution.com/shipments/airbills/8051/original.pdf?1335300069",
         "ship_to_name":"John Doe",
         "items":[
            {
               "price":"189.0",
               "quantity":1,
               "id":"253",
               "ticket_group":{
                  "url":"/ticket_groups/7365936",
                  "remote_id":"4577",
                  "office_id":1026,
                  "retail_price":null,
                  "quantity":null,
                  "wholesale_price":189.0,
                  "event":{
                     "url":"/events/117655",
                     "occurs_at":"2011-10-30T16:15:00Z",
                     "venue":{
                        "address":null,
                        "name":"Heinz Field",
                        "id":"1567"
                     },
                     "name":"Pittsburgh Steelers vs. New England Patriots",
                     "id":"117655"
                  },
                  "external_notes":null,
                  "section":"144",
                  "seats":[

                  ],
                  "row":"B",
                  "id":"7365936"
               }
            }
         ],
         "phone_number":{
            "extension":null,
            "number":"123-243-6697",
            "country_code":null,
            "label":"work",
            "id":"1912"
         },
         "name":null,
         "tracking_number":"798766684568",
         "signature_type":"",
         "id":"8051"
      }
   ]
}

Parameters

Name	Value	Description
order_id	Required	ID of the order that the shipment will belong to
items	Required	An array of the items on a shipment
type	Required	Type of shipment ("FedEx", "WillCall", "Courier", "UPS"). You cannot update a shipment type after it has been created. You must "cancel" a shipment and create a new one.
tracking_number	Optional	Tracking number of this shipment once it is created
phone_number_attributes	Optional	Array of phone numbers, just as they are found in the phone numbers endpoint. This is required for shipments that will generate an airbill via FedEx.
ship_to_company_name	Optional	Name of the company that is being shipped to
signature_type	Optional	"NO_SIGNATURE_REQUIRED", "ADULT", "DIRECT", "INDIRECT", "SERVICE_DEFAULT". This is required for shipments that will generate an airbill via FedEx.
service_type	Optional	To get a list of FedEx service types your company currently has configured you can use the /settings/shipping endpoint. (FEDEX_2_DAY, PRIORITY_OVERNIGHT, LEAST_EXPENSIVE). This is required for shipments that will generate an airbill via FedEx.
address_id	Optional	The ID of an existing address.
ship_to_name	Optional	Name of recipient. This is required for shipments that will generate an airbill via FedEx.
airbill	Optional	This should be a Base64 encoded file
address_attributes	Optional	Array of addresses, just as are found in the addresses endpoint

Update
PUT /shipment/:shipment_id

Shipments can only be updated if the shipment state is "pending".

Sample Code

Sample Request Body

{"tracking_number":"7112 3589 5648","type":"FedEx","airbill":"JVBERi0xLjINCg0KMyAwIG9iag0KPDwNCi9FIDc0OTA5DQovSCB…","ship_to_company_name":"Test Company"}

Sample Response

{
                         "airbill" => "http://s3.amazonaws.com/media.sandbox.ticketevolution.com/shipments/airbills/969/original.pdf?1327190774",
                            "type" => "FedEx",
                         "address" => nil,
                           "order" => {
                 "id" => "4621",
                "url" => "/orders/4621"
            },
            "service_type_display" => nil,
                    "service_type" => nil,
                    "ship_to_name" => nil,
            "ship_to_company_name" => "Test Company",
                    "phone_number" => nil,
                  "signature_type" => nil,
                           "state" => "pending",
                            "name" => nil,
                             "url" => "/shipments/969",
                      "updated_at" => "2012-08-30T14:53:51Z",
                 "tracking_number" => "7987 6668 4568",
                              "id" => "969",
                           "items" => [
                [0] {
                    "ticket_group" => {
                             "office_id" => 760,
                                   "row" => "67",
                                 "seats" => [],
                               "section" => "205",
                                 "event" => {
                                "venue" => {
                                "address" => nil,
                                   "name" => "Folsom Field Stadium",
                                     "id" => "516"
                            },
                            "occurs_at" => "2011-11-12T00:00:00Z",
                                 "name" => "Colorado Buffaloes vs. Arizona Wildcats",
                                  "url" => "/events/95662",
                                   "id" => "95662"
                        },
                              "quantity" => nil,
                        "external_notes" => nil,
                             "remote_id" => "8647",
                                   "url" => "/ticket_groups/9618467",
                                    "id" => "9618467"
                    },
                        "quantity" => 5,
                              "id" => "1293"
                }
            ]
}

Parameters

Name	Value	Description
shipment_id	Required	ID of the shipment being updated
tracking_number	Optional	Tracking number of the shipment.
service_type	Optional	To get a list of FedEx service types your company currently has configured you can use the /settings/shipping endpoint. (FEDEX_2_DAY, PRIORITY_OVERNIGHT, LEAST_EXPENSIVE)
signature_type	Optional	NO_SIGNATURE_REQUIRED, ADULT, DIRECT, INDIRECT, SERVICE_DEFAULT This is required for shipments that will generate an airbill via FedEx.
ship_to_company_name	Optional	Name of the company that is being shipped to
address_id	Optional	The ID of an existing address.
address_attributes	Optional	An address hash, just as are found in the addresses endpoint
phone_number_attributes	Optional	Pass a phone number
airbill	Optional	This should be a Base64 encoded file
ship_to_name	Optional	Name of recipient. This is required for shipments that will generate an airbill via FedEx.

Create Airbill
POST /shipments/:shipment_id/airbill

Sample Code

Sample Response

Parameters

Cancel
PUT /shipments/:shipment_id/cancel

You can only cancel a FedEx or WillCall shipment if they are in the "pending" state. If the shipment is a FedEx shipment, this call will attempt to notify FedEx to cancel the airbill.

Shipments

List GET /shipments

Sample Code

Sample Response

Parameters

Show GET /shipments/:shipment_id

Sample Code

Sample Response

Parameters

Create POST /shipments

Sample Code

Sample Request Body

Sample Response

Parameters

Update PUT /shipment/:shipment_id

Sample Code

Sample Request Body

Sample Response

Parameters

Create Airbill POST /shipments/:shipment_id/airbill

Sample Code

Sample Response

Parameters

Cancel PUT /shipments/:shipment_id/cancel

Sample Code

Sample Response

Parameters

Set Auth Credentials

List
GET /shipments

Show
GET /shipments/:shipment_id

Create
POST /shipments

Update
PUT /shipment/:shipment_id

Create Airbill
POST /shipments/:shipment_id/airbill

Cancel
PUT /shipments/:shipment_id/cancel