-
Notifications
You must be signed in to change notification settings - Fork 5
/
openapi.yaml
10865 lines (10079 loc) · 363 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.3
info:
title: Shippo external API.
description: Use this API to integrate with the Shippo service
version: '2018-02-08'
contact:
name: Shippo Developer Platform
url: https://goshippo.com/contact/
x-konfig-ignore:
object-with-no-properties: true
potential-incorrect-type: true
servers:
- url: https://api.goshippo.com
tags:
- description: >-
Carriers are the companies who deliver your package. Shippo uses Carrier
account objects as credentials to retrieve shipping rates and purchase
labels from shipping Carriers.
<SchemaDefinition schemaRef="#/components/schemas/CarrierAccount"/>
name: Carrier Accounts
- description: >-
A batch is a technique for creating multiple labels at once. Use the
batch object to create and purchase many shipments in two API calls. After
creating the batch, retrieve the batch to verify that all shipments are
valid. You can add and remove shipments after you have created the batch.
When all shipments are valid you can purchase the batch and retrieve all
the shipping labels.
<SchemaDefinition schemaRef="#/components/schemas/Batch"/>
# Batch Shipment
The batch shipment object is a wrapper around a shipment object, which
include shipment-specific information
for batch processing.
Note: batch shipments can only be created on the batch endpoint, either
when creating a batch object or by through
the `/batches/{BATCH_OBJECT_ID}/add_shipments` endpoint
<SchemaDefinition schemaRef="#/components/schemas/BatchShipment"/>
name: Batches
- description: >-
A user parcel template represents a package used for shipping that has
preset dimensions and attributes defined
by you. They are useful for capturing attributes of parcel-types you
frequently use for shipping, allowing
them to be defined once and then used for many shipments. These parcel
templates can also be used for live rates.
User parcel templates can also be created using a carrier parcel template,
where the dimensions will be copied from
the carrier presets, but the weight can be configured by you.
<SchemaDefinition schemaRef="#/components/schemas/UserParcelTemplate"/>
name: User Parcel Templates
- description: >-
Addresses are the locations a parcel is being shipped **from** and **to**.
They represent company and residential places. Among other things, you can
use address objects to create shipments, calculate shipping rates, and
purchase shipping labels.
<SchemaDefinition schemaRef="#/components/schemas/Address"/>
name: Addresses
- description: >-
A service group is a set of service levels grouped together.
Rates at checkout uses services groups to present available shipping
options to customers in their shopping basket.
<SchemaDefinition schemaRef="#/components/schemas/ServiceGroup"/>
name: Service Groups
- description: >-
Rates at checkout is a tool for merchants to display up-to-date shipping
estimates based on what's in their customers cart and where they’re
shipping to.
Merchants set up curated shipping options for customers in the checkout
flow based on data in the shopping cart. The request must include the
**to** address and item information. Optional fields are the **from**
address and package information. If the optional fields are not included,
the service will use the default address and/or package configured for
rates at checkout. The response is a list of shipping options based on the
Service Group configuration.
(see <a href="#tag/Service-Groups">Service Group configuration</a> for
details).
<SchemaDefinition schemaRef="#/components/schemas/LiveRate"/>
# Default Parcel Template
Assign one of your user parcel templates to be the default used when
generating Live Rates. This template will be used by default when
generating Live Rates, unless you explicitly provide a parcel in the Live
Rates request.
<SchemaDefinition schemaRef="#/components/schemas/UserParcelTemplate"/>
name: Rates at Checkout
- description: >-
Shippo Accounts are used by Shippo Platform Accounts to create and manage
Managed Shippo Accounts.
Managed Shippo Accounts are headless accounts that represent your
customers. They are opaque to your end customers, meaning customers do not
need to create their own Shippo login or have a billing relationship with
Shippo.
They can be used by marketplaces, e-commerce platforms, and third-party
logistics providers who want to offer, seamless, built-in shipping
functionality to their customers.
<SchemaDefinition schemaRef="#/components/schemas/ShippoAccount"/>
name: Shippo Accounts
- description: >-
A parcel is an item you are shipping. The parcel object includes details
about its physical make-up of the parcel. It includes dimensions and
weight that Shippo uses to calculate rates.
<SchemaDefinition schemaRef="#/components/schemas/Parcel"/>
# Parcel Extras
The following values are supported for the `extra` field of the parcel
object.
<SchemaDefinition schemaRef="#/components/schemas/ParcelExtra"/>
name: Parcels
- description: >-
A shipment is the act of transporting goods. A shipment object contains
**to** and **from** addresses, and the parcel details that you are
shipping. You can use the shipment object to retrieve shipping rates and
purchase a shipping label.
<SchemaDefinition schemaRef="#/components/schemas/Shipment"/>
# Shipment Extras
The following values are supported for the `extra` field of the shipment
object.
<SchemaDefinition schemaRef="#/components/schemas/ShipmentExtra"/>
name: Shipments
- description: >-
A rate is the cost to ship a parcel from a carrier. The rate object
details the service level including the cost and transit time.
<SchemaDefinition schemaRef="#/components/schemas/Rate"/>
name: Rates
- description: >-
A transaction is the purchase of a shipping label from a shipping provider
for a specific service. You can print purchased labels and used them to
ship a parcel with a carrier, such as USPS or FedEx.
<SchemaDefinition schemaRef="#/components/schemas/Transaction"/>
name: Transactions
x-displayName: Transactions (shipping labels)
- description: >-
Customs declarations are relevant information, including one or multiple
customs items, you need to provide for customs clearance for your
international shipments.
<SchemaDefinition schemaRef="#/components/schemas/CustomsItem"/>
name: Customs Items
- description: >-
Customs declarations are relevant information, including one or multiple
customs items, you need to provide for
customs clearance for your international shipments.
<SchemaDefinition schemaRef="#/components/schemas/CustomsDeclaration"/>
name: Customs Declarations
- description: >-
A manifest is a single-page document with a barcode that carriers can scan
to accept all packages into transit without the need to scan each item
individually.
They are close-outs of shipping labels of a certain day. Some carriers
require manifests to process the shipments.
<SchemaDefinition schemaRef="#/components/schemas/Manifest"/>
# Manifest Errors
The following codes and messages are the possible errors that may occur
when creating Manifests.
<SchemaDefinition schemaRef="#/components/schemas/ManifestErrors"/>
name: Manifests
- description: >-
An order is a request from a customer to purchase goods from a merchant.
Use the orders object to load orders from your system to the Shippo
dashboard.
You can use the orders object to create, retrieve, list, and manage orders
programmatically.
You can also retrieve shipping rates, purchase labels, and track shipments
for each order.
<SchemaDefinition schemaRef="#/components/schemas/Order"/>
# Line Item
<p style="text-align: center; background-color: #F2F3F4;">
</br>Line Items, and their corresponding abstract Products and Variants, might be exposed as a separate resource
in the future. Currently it's a nested object within the order resource.</br></br>
</p>
A line item is an individual object in an order. For example, if your order contains a t-shirt, shorts, and a jacket, each item is represented by a line item.
<SchemaDefinition schemaRef="#/components/schemas/LineItem"/>
name: Orders
x-displayName: Orders (beta)
- description: >-
Refunds are reimbursements for successfully created but unused shipping
labels or other charges.
<SchemaDefinition schemaRef="#/components/schemas/Refund"/>
name: Refunds
- description: >-
<p style="text-align: center; background-color: #F2F3F4;"></br>
If you purchased your shipping label through Shippo, you can also get all
the tracking details of your Shipment
from the <a href="#tag/Transactions">Transaction</a> object.
</br></br></p>
A tracking status of a package is an indication of current location of a
package in the supply chain. For example, sorting, warehousing, or out
for delivery. Use the tracking status object to track the location of your
shipments.
When using your <a
href="https://docs.goshippo.com/docs/guides_general/authentication/">Test</a>
token for tracking, you need to use Shippo's
predefined tokens for testing different tracking statuses. You can find
more information in our
<a href="https://docs.goshippo.com/docs/tracking/tracking/">Tracking
tutorial</a> on how to do this, and what the
payloads look like.
<SchemaDefinition schemaRef="#/components/schemas/Track"/>
name: Tracking Status
- description: >-
A carrier parcel template represents a package used for shipping that has
preset dimensions defined by a carrier. Some examples of a carrier parcel
template include USPS Flat Rate Box and Fedex Small Pak. When using a
carrier parcel template, the rates returned may be limited to the carrier
that provides the box. You can create user parcel templates using a
carrier parcel template. Shippo takes the dimensions of the carrier parcel
template but you must configure the weight.
<SchemaDefinition schemaRef="#/components/schemas/CarrierParcelTemplate"/>
name: Carrier Parcel Templates
- description: >-
A pickup is when you schedule a carrier to collect a package for delivery.
Use Shippo’s pickups endpoint to schedule pickups with USPS and DHL
Express for eligible shipments that you have already created.
<SchemaDefinition schemaRef="#/components/schemas/Pickup"/>
name: Pickups
- description: >-
<p style="text-align: center; background-color: #F2F3F4;">
</br>First-time users and those looking for specific integration tutorials,
<a href="https://docs.goshippo.com">see our full API documentation and guides.</a><br>
Download the <a href="https://docs.goshippo.com/spec/shippoapi/public-api.yaml">API Specification yaml file</a>
</p>
<h3>API Resources</h3>
All API URLs listed in this documentation are relative to
<b>https://api.goshippo.com/</b>.
For example, the `/addresses/` resource is reachable at
`https://api.goshippo.com/addresses/`.
<h3>Authentication</h3>
The API requires Shippo's token HTTP Authentication with your Shippo token
(live or test).
In order to authenticate properly, please put `Authorization: ShippoToken
<token>` in your header. You can find your token on the
<a href="https://goshippo.com/user/apikeys/">Shippo API settings page</a>.
For more information about authentication and test mode,
<a
href="https://docs.goshippo.com/docs/guides_general/authentication/">please
visit our Authentication guide</a>.
The API is available via Secure Socket Layer (SSL) only. All requests to
the Shippo API must use TLS version 1.2 or higher.
<h3>Request & Response Data</h3>
Request data is passed to the API by <b>POSTing JSON objects</b> with the
appropriate key/value-pairs to the respective
resource. The documentation for each API resource contains more details on
the values accepted by a given resource.
Response data also formatted as JSON object. You can specify how many
results per page are to be returned. For instance,
`/rates/?results=25` will return up to 25 results.
<h3>REST & Disposable Objects</h3>
The Shippo API is built around <a
href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST
principles</a>.
Use POST requests to create objects, GET requests to retrieve objects, and
PUT requests to update objects.
Only the Carrier Accounts object can be updated via PUT requests. All
other objects such as Addresses, Parcels,
Shipments, Rates, Transactions, Refunds, Customs Items, and Customs
Declarations are disposable. This means that
once you have created an object, you cannot change it. Instead, create a
new one with the desired values.
<h3>API Version</h3>
This reference guide supports the Shippo API version: `2018-02-08` .
To see reference guides for older API versions, see our <a
href="https://docs.goshippo.com/docs/guides_general/legacy_reference/">legacy
reference guide</a>.
For more information about Shippo API versions, see our <a
href="https://docs.goshippo.com/docs/api_concepts/apiversioning/">API
versions guide</a>.
name: Overview
- description: <SchemaDefinition schemaRef="#/components/schemas/CarriersEnum"/>
name: Carriers
- description: <SchemaDefinition schemaRef="#/components/schemas/ServiceLevelEnumSet"/>
name: Service Levels
- description: >-
A predefined package used by one or multiple carriers. See below for all
available values and the corresponding tokens.
When a template is given, the parcel dimensions do not have to be sent,
the dimensions below will instead be used.
The parcel weight is not affected by the use of a template.
<SchemaDefinition schemaRef="#/components/schemas/ParcelTemplateEnumSet"/>
name: Parcel Templates
paths:
/addresses:
get:
tags:
- Addresses
summary: List all addresses
operationId: Addresses_listAll
description: >-
Returns a list of all address objects that have been created in this
account.
parameters:
- $ref: '#/components/parameters/PageNumberQueryParam'
- $ref: '#/components/parameters/ResultsPerPageDefault5QueryParam'
- $ref: '#/components/parameters/ShippoApiVersionHeader'
responses:
'200':
$ref: '#/components/responses/addressPaginatedResponse'
x-code-samples:
- label: cURL
lang: cURL
source: |-
curl https://api.goshippo.com/addresses/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
- label: Python
lang: Python
source: |-
# List all addresses
shippo.Address.all()
- label: Ruby
lang: Ruby
source: |-
# List all addresses
Shippo::Address.all()
- label: Node
lang: Node
source: |-
// List all addresses
shippo.address.list();
- label: PHP
lang: PHP
source: |-
// List all addresses
Shippo_Address::all();
post:
tags:
- Addresses
summary: Create a new address
operationId: Addresses_createNewAddress
description: >-
Creates a new address object. You can use address objects to create new
shipments, calculate rates, and to create orders.
parameters:
- $ref: '#/components/parameters/ShippoApiVersionHeader'
requestBody:
description: Address details.
content:
application/json:
schema:
$ref: '#/components/schemas/AddressCreateRequest'
responses:
'201':
$ref: '#/components/responses/addressResponse'
x-code-samples:
- label: cURL
lang: cURL
source: |-
curl https://api.goshippo.com/addresses/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-d name="Shawn Ippotle" \
-d company="Shippo" \
-d street1="215 Clayton St." \
-d street2="" \
-d city="San Francisco" \
-d state="CA" \
-d zip=94117 \
-d country="US" \
-d phone="+1 555 341 9393" \
-d email="shippotle@shippo.com"\
-d is_residential=True\
-d metadata="Customer ID 123456"
- label: Python
lang: Python
source: |-
# Create address object
address_from = shippo.Address.create(
name="Shawn Ippotle",
company="Shippo",
street1="215 Clayton St.",
city="San Francisco",
state="CA",
zip="94117",
country="US", # iso2 country code
phone="+1 555 341 9393",
email="shippotle@shippo.com"
)
- label: Ruby
lang: Ruby
source: |-
# Create address object
address_from = Shippo::Address.create(
:name => "Shawn Ippotle",
:company => "Shippo",
:street1 => "Clayton St.",
:street_no => "215",
:street2 => "",
:city => "San Francisco",
:state => "CA",
:zip => "94117",
:country => "US",
:phone => "+1 555 341 9393",
:email => "shippotle@shippo.com"
)
- label: Node
lang: Node
source: |-
// Create address object
var addressFrom = shippo.address.create({
"name":"Shawn Ippotle",
"company":"Shippo",
"street1":"215 Clayton St.",
"city":"San Francisco",
"state":"CA",
"zip":"94117",
"country":"US", // iso2 country code
"phone":"+1 555 341 9393",
"email":"shippotle@shippo.com",
})
- label: PHP
lang: PHP
source: |-
// Create address object
$fromAddress = Shippo_Address::create( array(
"name" => "Shawn Ippotle",
"company" => "Shippo",
"street1" => "215 Clayton St.",
"city" => "San Francisco",
"state" => "CA",
"zip" => "94117",
"country" => "US",
"phone" => "+1 555 341 9393",
"email" => "shippotle@shippo.com"
));
/addresses/{AddressId}:
get:
tags:
- Addresses
summary: Retrieve an address
operationId: Addresses_getAddressById
description: Returns an existing address using an object ID.
parameters:
- description: Object ID of the address
in: path
name: AddressId
required: true
schema:
type: string
- $ref: '#/components/parameters/ShippoApiVersionHeader'
responses:
'200':
$ref: '#/components/responses/addressResponse'
x-code-samples:
- label: cURL
lang: cURL
source: >-
curl
https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/
\
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
- label: Python
lang: Python
source: |-
# Retrieve an existing address by object_id
shippo.Address.retrieve("d799c2679e644279b59fe661ac8fa488")
- label: Ruby
lang: Ruby
source: |-
# Retrieve an existing address by object_id
Shippo::Address.get('d799c2679e644279b59fe661ac8fa488')
- label: Node
lang: Node
source: |-
// Retrieve an existing address by object_id
shippo.address.retrieve('d799c2679e644279b59fe661ac8fa488');
- label: PHP
lang: PHP
source: |-
// Retrieve an existing address by object_id
Shippo_Address::retrieve('d799c2679e644279b59fe661ac8fa488');
/addresses/{AddressId}/validate:
get:
tags:
- Addresses
summary: Validate an address
operationId: Addresses_validateAddress
description: Validates an existing address using an object ID
parameters:
- description: Object ID of the address
in: path
name: AddressId
required: true
schema:
type: string
- $ref: '#/components/parameters/ShippoApiVersionHeader'
responses:
'200':
$ref: '#/components/responses/addressResponse'
x-code-samples:
- label: cURL
lang: cURL
source: >-
curl
https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/
\
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
- label: Python
lang: Python
source: |-
# Validate an existing address by object_id
shippo.Address.validate('d799c2679e644279b59fe661ac8fa488')
- label: Ruby
lang: Ruby
source: |-
# Validate an existing address by object_id
Shippo::Address.get("d799c2679e644279b59fe661ac8fa488").validate()
- label: Node
lang: Node
source: >-
// Validate an existing address by object_id
shippo.address.validate("d799c2679e644279b59fe661ac8fa488",
function(err, address) {
// asynchronously called
});
- label: PHP
lang: PHP
source: |-
// Validate an existing address by object_id
Shippo_Address::validate('d799c2679e644279b59fe661ac8fa488');
x-speakeasy-name-override: validate
/batches:
post:
tags:
- Batches
summary: Create a batch
operationId: Batches_createBatchShipments
description: >-
Creates a new batch object for purchasing shipping labels for many
shipments at once. Batches are created asynchronously. This means that
the API response won't include your batch shipments yet. You need to
retrieve the batch later to verify that all batch shipments are valid.
parameters:
- $ref: '#/components/parameters/ShippoApiVersionHeader'
requestBody:
description: Batch details.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateRequest'
responses:
'200':
$ref: '#/components/responses/batchResponse'
x-code-samples:
- label: cURL
lang: cURL
source: >-
curl https://api.goshippo.com/batches/ \
-H "Authorization: ShippoToken
shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-H "Content-Type: application/json" \
-d '{
"default_carrier_account": "078870331023437cb917f5187429b093",
"default_servicelevel_token": "usps_priority",
"label_filetype": "PDF_4x6",
"metadata": "BATCH #170",
"batch_shipments": [
{
"shipment": {
"address_from": {
"name": "Mr Hippo",
"street1": "965 Mission St",
"street2": "Ste 201",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@shippo.com"
},
"address_to": {
"name": "Mrs Hippo",
"company": "",
"street1": "Broadway 1",
"street2": "",
"city": "New York",
"state": "NY",
"zip": "10007",
"country": "US",
"phone": "4151234567",
"email": "mrshippo@shippo.com"
},
"parcels": [{
"length": "5",
"width": "5",
"height": "5",
"distance_unit": "in",
"weight": "2",
"mass_unit": "oz"
}]
}
},
{
"shipment": {
"address_from": {
"name": "Mr Hippo",
"street1": "1092 Indian Summer Ct",
"city": "San Jose",
"state": "CA",
"zip": "95122",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@shippo.com"
},
"address_to": {
"name": "Mrs Hippo",
"company": "",
"street1": "Broadway 1",
"street2": "",
"city": "New York",
"state": "NY",
"zip": "10007",
"country": "US",
"phone": "4151234567",
"email": "mrshippo@shippo.com"
},
"parcels": [{
"length": "5",
"width": "5",
"height": "5",
"distance_unit": "in",
"weight": "20",
"mass_unit": "lb"
}]
},
"carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
"servicelevel_token": "fedex_2_day"
}
]
}'
- label: Python
lang: Python
source: |-
batch = shippo.Batch.create(
default_carrier_account="078870331023437cb917f5187429b093",
default_servicelevel_token="usps_priority",
label_filetype="PDF_4x6",
metadata="this is metadata",
batch_shipments=[
{
"shipment": {
"address_from": {
"name": "Mr Hippo",
"street1": "965 Mission St",
"street2": "Ste 201",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
},
"address_to": {
"name": "Mrs Hippo",
"company": "",
"street1": "Broadway 1",
"street2": "",
"city": "New York",
"state": "NY",
"zip": "10007",
"country": "US",
"phone": "4151234567",
},
"parcels": [{
"length": "5",
"width": "5",
"height": "5",
"distance_unit": "in",
"weight": "2",
"mass_unit": "oz"
}]
}
},
{
"shipment": {
"address_from": {
"name": "Mr Hippo",
"street1": "1092 Indian Summer Ct",
"city": "San Jose",
"state": "CA",
"zip": "95122",
"country": "US",
"phone": "4151234567",
},
"address_to": {
"name": "Mrs Hippo",
"company": "",
"street1": "Broadway 1",
"street2": "",
"city": "New York",
"state": "NY",
"zip": "10007",
"country": "US",
"phone": "4151234567",
},
"parcels": [{
"length": "5",
"width": "5",
"height": "5",
"distance_unit": "in",
"weight": "20",
"mass_unit": "lb"
}]
}
}
]
)
- label: Ruby
lang: Ruby
source: |-
Shippo::batch.create({
:default_carrier_account => DEFAULT_CARRIER_ACCOUNT,
:default_servicelevel_token => 'usps_priority',
:label_filetype => 'ZPLII',
:metadata => 'BATCH #170',
:batch_shipments => [
{
:shipment => {
:address_from => address_from_one,
:address_to => address_to_one,
:parcel => parcel_one,
:async => false
}
},
{
:shipment => {
:address_from => address_from_two,
:address_to => address_to_two,
:parcel => parcel_two,
:async => false
}
}
]
})
- label: Node
lang: Node
source: |-
var batch = shippo.batch.create({
"default_carrier_account": "078870331023437cb917f5187429b093",
"default_servicelevel_token": "usps_priority",
"label_filetype": "PDF_4x6",
"metadata": "BATCH #170",
"batch_shipments": [
{
"shipment": {
"address_from": addressFromOne,
"address_to": addressToOne,
"parcels": parcelsOne
}
},
{
"shipment": {
"address_from": addressFromTwo,
"address_to": addressToTwo,
"parcels": parcelsTwo
}
}
]
})
- label: PHP
lang: PHP
source: |-
$batch = Shippo_Batch::create(array(
'default_carrier_account' => $carrier,
'default_servicelevel_token' => 'usps_priority',
'label_filetype' => 'PDF_4x6',
'metadata' => '',
'batch_shipments' => array(
array(
'shipment' => array(
'address_from' => array(
'name' => 'Mr Hippo',
'street1' => '965 Mission St',
'street2' => 'Ste 201',
'city' => 'San Francisco',
'state' => 'CA',
'zip' => '94103',
'country' => 'US',
'phone' => '4151234567',
'email' => 'mrhippo@shippo.com'
),
'address_to' => array(
'name' => 'Mrs Hippo',
'company' => '',
'street1' => 'Broadway 1',
'street2' => '',
'city' => 'New York',
'state' => 'NY',
'zip' => '10007',
'country' => 'US',
'phone' => '4151234567',
'email' => 'mrshippo@shippo.com'
),
'parcels' => array(
array(
'length' => '5',
'width' => '5',
'height' => '5',
'distance_unit' => 'in',
'weight' => '2',
'mass_unit' => 'oz'
)
)
)
)
)
))
/batches/{BatchId}:
get:
tags:
- Batches
summary: Retrieve a batch
operationId: Batches_getBatchById
description: >-
Returns a batch using an object ID. <br> Batch shipments are displayed
100 at a time. You can iterate
through each `page` using the `?page= query` parameter. You can also
filter based on batch shipment
status, for example, by passing a query param like
`?object_results=creation_failed`. <br>
For more details on filtering results, see our guide on <a
href="https://docs.goshippo.com/docs/api_concepts/filtering/"
target="blank"> filtering</a>.
parameters:
- description: Object ID of the batch
in: path
name: BatchId
required: true
schema:
type: string
- $ref: '#/components/parameters/ShippoApiVersionHeader'
responses:
'200':
$ref: '#/components/responses/batchResponse'
x-code-samples:
- label: cURL
lang: cURL
source: >-
curl https://api.goshippo.com/batches/<BATCH OBJECT
ID>?page=2&object_results=creation_failed \
-H "Authorization: ShippoToken
shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
- label: Python
lang: Python
source: shippo.Batch.retrieve(batch_object_id)
- label: Ruby
lang: Ruby
source: Shippo::batch.retrieve(batch_object_id)
- label: Node
lang: Node
source: shippo.batch.retrieve(batchObjectId)
- label: PHP
lang: PHP
source: Shippo_Batch::retrieve($batch_object_id)
/batches/{BatchId}/add_shipments:
post:
tags:
- Batches
summary: Add shipments to a batch
operationId: Batches_addShipmentsToBatch
description: Adds batch shipments to an existing batch.
parameters:
- description: Object ID of the batch
in: path
name: BatchId
required: true
schema:
type: string
- $ref: '#/components/parameters/ShippoApiVersionHeader'
requestBody:
description: Array of shipments to add to the batch
content:
application/json:
schema:
$ref: '#/components/schemas/BatchesAddShipmentsToBatchRequest'
responses:
'200':
$ref: '#/components/responses/batchResponse'
x-code-samples:
- label: cURL
lang: cURL
source: >-
curl -X POST https://api.goshippo.com/batches/<BATCH OBJECT