openapi: 3.2.0
info:
  title: Overview Pickups API
  version: '1.0'
  summary: API Overview
  contact:
    name: AfterShip Support
    url: https://www.aftership.com/contact-us
    email: support@aftership.com
  termsOfService: https://www.aftership.com/legal/terms-of-service
  description: '> OAS Schema can be downloaded [here](https://stoplight.io/api/v1/projects/automizely/docs-core-postmenapi-com/nodes/reference/api.v3.json?branch=master&deref=optimizedBundle)'
servers:
- description: Sandbox
  url: https://sandbox-api.aftership.com/postmen/v3
- url: https://api.aftership.com/postmen/v3
  description: Production
security:
- as-api-key: []
tags:
- name: Pickups
paths:
  /pickups:
    parameters: []
    get:
      summary: Get pickups
      tags:
      - Pickups
      responses:
        '200':
          description: Get pickups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta.v3'
                    x-stoplight:
                      id: b12ngg1c7syup
                  data:
                    type: object
                    x-stoplight:
                      id: hz9jv3ziseone
                    properties:
                      next_token:
                        type: string
                        x-stoplight:
                          id: 71delszk06u73
                      limit:
                        type: integer
                        x-stoplight:
                          id: 4092m31rttp3o
                      created_at_min:
                        type: string
                        x-stoplight:
                          id: vt4cxtyfc8rf2
                      created_at_max:
                        type: string
                        x-stoplight:
                          id: j97u7svzz4kg8
                      pickups:
                        type: array
                        description: This array contains all pickups data. Please refer to [pickup](../model/resource/pickup.v3.json) object for pickup object details.
                        items:
                          $ref: '#/components/schemas/Pickup.v3'
                          x-stoplight:
                            id: s92w5qsob768y
              examples:
                Get User Alice Smith:
                  value:
                    meta:
                      code: 200
                      type: OK
                      message: Everything worked as expected.
                    data:
                      next_token: string
                      limit: 0
                      created_at_min: string
                      created_at_max: string
                      pickups:
                      - id: 00000000-0000-0000-0000-000000000000
                        status: created
                        pickup_confirmation_numbers:
                        - 00000000-0000-0000-0000-000000000000
                        pickup_date: '2023-09-10'
                        pickup_start_time: 09:00:00
                        pickup_end_time: '18:00:00'
                        pickup_from:
                          company_name: AfterShip Shipping
                          contact_name: AfterShip Shipping
                          street1: 230 W 200 S LBBY
                          city: Salt Lake City
                          state: UT
                          postal_code: '84101'
                          country: USA
                          phone: '123456789'
                          email: test@test.com
                          type: business
                        label_ids:
                        - 00000000-0000-0000-0000-000000000000
                        created_at: '2022-05-09T07:54:13.024Z'
                        updated_at: '2022-09-09T07:54:24.569Z'
      operationId: get-pickups
      description: 'Get pickups.

        <div style="visibility:hidden; height: 0">

        This array contains all pickups data. Please refer to [pickup](../model/resource/pickup.v3.json) object for pickup object details.

        </div>'
      x-stoplight:
        id: x8mxu5wa7m6y3
      parameters:
      - schema:
          type: string
          default: application/json
          example: application/json
        in: header
        name: Content-Type
        description: Content-Type
        required: true
      - schema:
          type: string
          enum:
          - creating
          - created
          - failed
          - cancelling
          - cancelled
        in: query
        name: status
        description: Pickup status
      - schema:
          type: string
        in: query
        name: limit
        description: Number of records per page
      - schema:
          type: string
        in: query
        name: created_at_min
        description: 'Start date and time of the record created (format YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+00:00, default: 24hrs ago)'
      - schema:
          type: string
        in: query
        name: created_at_max
        description: 'End date and time of the record created (format YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+00:00, default: NOW())'
      - schema:
          type: string
        in: query
        name: next_token
        description: The 'next_token' is a short code provided in the response when there are more 'pickup' records to fetch. Use this code in your next request to get the next batch of records. If 'next_token' is not included or is null, it means there are no more records to fetch.
      requestBody:
        content: {}
      security:
      - as-api-key: []
    post:
      summary: Create a pickup
      operationId: post-pickups
      responses:
        '200':
          description: Create a pickup object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta.v3'
                    x-stoplight:
                      id: drqimdnbxyqxh
                  data:
                    $ref: '#/components/schemas/Pickup.v3'
              examples:
                Example 1:
                  value:
                    meta:
                      code: 200
                      type: OK
                      message: Everything worked as expected.
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      status: created
                      pickup_confirmation_numbers:
                      - '3012'
                      pickup_date: '2023-09-21'
                      pickup_start_time: 09:00:00
                      pickup_end_time: '18:00:00'
                      pickup_from:
                        contact_name: AfterShip Shipping
                        company_name: AfterShip Shipping
                        street1: 230 W 200 S LBBY
                        city: Salt Lake City
                        state: UT
                        postal_code: '84101'
                        country: USA
                        phone: '123456789'
                        email: test@test.com
                      ship_to: null
                      label_ids:
                      - 00000000-0000-0000-0000-000000000000
                      shipper_account:
                        id: 00000000-0000-0000-0000-000000000000
                        slug: fedex
                      pickup_parcels:
                      - weight:
                          value: 1
                          unit: lb
                        quantity: 1
                      created_at: '2023-09-21T07:54:13.024Z'
                      updated_at: '2023-09-21T07:54:13.024Z'
                Example 2:
                  value:
                    meta:
                      code: 200
                      type: OK
                      message: Everything worked as expected.
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      status: created
                      pickup_confirmation_numbers:
                      - '3012'
                      pickup_date: '2023-09-21'
                      pickup_start_time: 09:00:00
                      pickup_end_time: '18:00:00'
                      pickup_from:
                        contact_name: AfterShip Shipping
                        company_name: AfterShip Shipping
                        street1: 230 W 200 S LBBY
                        city: Salt Lake City
                        state: UT
                        postal_code: '84101'
                        country: USA
                        phone: '123456789'
                        email: test@test.com
                      ship_to:
                        contact_name: AfterShip Shipping
                        company_name: AfterShip Shipping
                        street1: 230 W 200 S LBBY
                        city: Salt Lake City
                        state: UT
                        postal_code: '84101'
                        country: USA
                        phone: '123456789'
                        email: test@test.com
                      label_ids:
                      - 00000000-0000-0000-0000-000000000000
                      shipper_account:
                        id: 00000000-0000-0000-0000-000000000000
                        slug: fedex
                      pickup_parcels:
                      - weight:
                          value: 1
                          unit: lb
                        quantity: 1
                      created_at: '2023-09-21T07:54:13.024Z'
                      updated_at: '2023-09-21T07:54:13.024Z'
      x-stoplight:
        id: bzel9ue0joeds
      description: Create a pickup. Applicable for `FedEx`, `UPS`, `DHL Express`, `Purolator`.
      parameters:
      - schema:
          type: string
          default: application/json
          example: application/json
        in: header
        name: Content-Type
        description: Content-Type
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - pickup_start_time
              - pickup_end_time
              - pickup_from
              properties:
                pickup_date:
                  type: string
                  x-stoplight:
                    id: nzg3a7ncu4kim
                  description: Pickup Date should be provided in YYYY-MM-DD format. If it is not provided, it will default to today's date in the shipper account's timezone
                pickup_start_time:
                  type: string
                  x-stoplight:
                    id: 5aybqbkpbkvof
                  description: Preferred start time for pickup in HH:mm:ss
                pickup_end_time:
                  type: string
                  x-stoplight:
                    id: kqrn97dqssrun
                  description: Preferred end time for pickup in HH:mm:ss
                pickup_from:
                  $ref: '#/components/schemas/Address.v3'
                ship_to:
                  $ref: '#/components/schemas/Address.v3'
                  x-stoplight:
                    id: gfssaoqcemwea
                label_ids:
                  type: array
                  x-stoplight:
                    id: og3rw1vwdrkq1
                  description: 'The id of labels that need to pickup.

                    If label_ids are present, pickup_parcels should not be present'
                  maxItems: 2000
                  items:
                    x-stoplight:
                      id: xyb2319oo959f
                    type: string
                pickup_parcels:
                  type: array
                  x-stoplight:
                    id: 3m9lc1210eszp
                  description: 'Parcel detail information which to be pickup.

                    If label_ids are not present, pickup_parcels are required.

                    When pickup_parcels are present, shipper_account is required'
                  items:
                    $ref: '#/components/schemas/Pickup_parcel.v3'
                    x-stoplight:
                      id: rg6vxf4hy1fwr
                shipper_account:
                  $ref: '#/components/schemas/Reference.v3'
                  x-stoplight:
                    id: ity0yuqq1x6lf
                  description: 'Shipper Account which register in Shipping.

                    If pickup_parcels are present, shipper_account is required'
                pickup_location:
                  x-stoplight:
                    id: ql2fpjonx9obc
                  description: Enum of shipments location which provided by the carrier. For more detailed information, please refer to the [help article](https://support.postmen.com/en/article/how-to-use-aftership-shipping-pickup-api-1qzsxsn/).
                  type: string
                pickup_instructions:
                  type: string
                  x-stoplight:
                    id: ulk7kzd9w7exg
                  description: If you have any instructions for the pickup, they can be used as a note for some carriers
                  maxLength: 255
            examples:
              Example 1:
                value:
                  pickup_date: '2023-09-21'
                  pickup_start_time: 09:00:00
                  pickup_end_time: '18:00:00'
                  pickup_from:
                    contact_name: AfterShip Shipping
                    company_name: AfterShip Shipping
                    street1: 230 W 200 S LBBY
                    city: Salt Lake City
                    state: UT
                    postal_code: '84101'
                    country: USA
                    phone: '123456789'
                    email: test@test.com
                  label_ids:
                  - 00000000-0000-0000-0000-000000000000
                  pickup_instructions: instructions
              Example 2:
                value:
                  pickup_date: '2023-09-21'
                  pickup_start_time: 09:00:00
                  pickup_end_time: '18:00:00'
                  pickup_from:
                    contact_name: AfterShip Shipping
                    company_name: AfterShip Shipping
                    street1: 230 W 200 S LBBY
                    city: Salt Lake City
                    state: UT
                    postal_code: '84101'
                    country: USA
                    phone: '123456789'
                    email: test@test.com
                  ship_to:
                    contact_name: AfterShip Shipping
                    company_name: AfterShip Shipping
                    street1: 230 W 200 S LBBY
                    city: Salt Lake City
                    state: UT
                    postal_code: '84101'
                    country: USA
                    phone: '123456789'
                    email: test@test.com
                  pickup_parcels:
                  - weight:
                      unit: lb
                      value: 1
                    quantity: 1
                    service_type: string
                  shipper_account:
                    id: 00000000-0000-0000-0000-000000000000
                  pickup_location: string
                  pickup_instructions: string
        description: Create a pickup object.
      security:
      - as-api-key: []
      tags:
      - Pickups
  /pickups/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
      description: Pickup id
    get:
      summary: Get a pickup
      operationId: get-pickup
      responses:
        '200':
          description: Get a pickup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta.v3'
                    x-stoplight:
                      id: 4mm1ym7u23xza
                  data:
                    $ref: '#/components/schemas/Pickup.v3'
              examples:
                Example 1:
                  value:
                    meta:
                      code: 200
                      type: OK
                      message: Everything worked as expected.
                    data:
                      id: 00000000-0000-0000-0000-000000000000
                      status: created
                      pickup_confirmation_numbers:
                      - 00000000-0000-0000-0000-000000000000
                      pickup_date: '2023-09-21'
                      pickup_start_time: 09:00:00
                      pickup_end_time: 09:00:00
                      pickup_from:
                        contact_name: AfterShip Shipping
                        company_name: AfterShip Shipping
                        street1: 230 W 200 S LBBY
                        city: Salt Lake City
                        state: UT
                        postal_code: '84101'
                        country: USA
                        phone: '123456789'
                        email: test@test.com
                      label_ids:
                      - 00000000-0000-0000-0000-000000000000
                      created_at: '2022-05-09T07:54:13.024Z'
                      updated_at: '2022-05-09T07:54:13.024Z'
      x-stoplight:
        id: ytjdnwbl7dqxb
      description: Get a pickup.
      parameters:
      - schema:
          type: string
          default: application/json
          example: application/json
        in: header
        name: Content-Type
        description: Content-Type
        required: true
      security:
      - as-api-key: []
      tags:
      - Pickups
components:
  schemas:
    Meta.v3:
      description: Meta data object.
      type: object
      x-examples: {}
      examples:
      - code: 200
        type: OK
        message: Everything worked as expected.
      title: Meta
      x-tags:
      - Envelope
      properties:
        code:
          type: integer
          description: Code of Meta
        message:
          type: string
          description: Message of Meta
        details:
          type: array
          description: Details of Meta
          items:
            $ref: '#/components/schemas/Error.v3'
        retryable:
          type: boolean
          description: Whether this request will be retryable or not
      required:
      - code
      - message
    Weight.v3:
      title: Weight
      x-stoplight:
        id: sqe056qqggctt
      type: object
      description: 'Weight object: unit weight of the item'
      x-tags:
      - Primitive
      examples: []
      properties:
        unit:
          type: string
          description: weight unit
          enum:
          - lb
          - kg
          - oz
          - g
        value:
          type: number
          description: value of Weight
      required:
      - unit
      - value
    Reference.v3:
      title: Reference
      x-stoplight:
        id: pwqp1323bhe8q
      type: object
      properties:
        id:
          type: string
          description: 'id of referring object

            '
      x-tags:
      - Primitive
      examples: []
      description: 'Reference object: the description of reference information'
    Pickup.v3:
      title: Pickup
      x-stoplight:
        id: dnu7w6c2lryrd
      type: object
      description: 'Pickup object: the description of pickup information'
      properties:
        id:
          type: string
          x-stoplight:
            id: 6shh25v9yirmh
          description: Pickup ID
        status:
          type: string
          x-stoplight:
            id: bgy62xipikko1
          enum:
          - creating
          - created
          - failed
          - cancelling
          - cancelled
        pickup_confirmation_numbers:
          type: array
          x-stoplight:
            id: xbigmmmrfzia7
          description: The confirmation numbers dispatch from carrier when pickup success
          items:
            x-stoplight:
              id: u8b77786y8vnt
            type: string
        pickup_location_code:
          type: string
          x-stoplight:
            id: uz99jzt40cpfl
          description: The pickup location code dispatch from carrier when pickup success
        pickup_date:
          type: string
          x-stoplight:
            id: uz99jzt40cpfl
          description: Pickup Date in YYYY-MM-DD
        pickup_start_time:
          type: string
          x-stoplight:
            id: k4gfz3e6csald
          description: A formatted date
        pickup_end_time:
          type: string
          x-stoplight:
            id: 0lkft6pgp7k4h
          description: A formatted date
        pickup_from:
          $ref: '#/components/schemas/Address.v3'
          x-stoplight:
            id: nbr45ggkh7584
          description: 'Address object: the description of pickup address information'
        ship_to:
          $ref: '#/components/schemas/Address.v3'
          x-stoplight:
            id: 6x1lv7sr6iaig
        label_ids:
          type: array
          x-stoplight:
            id: y481cmhzpq3qi
          description: Labels array, it contains all the label need to pickup
          items:
            x-stoplight:
              id: yovnn28g7hvny
            type: string
        pickup_parcels:
          x-stoplight:
            id: qa1rp9rr56de3
          type: array
          description: Parcel detail information
          items:
            $ref: '#/components/schemas/Pickup_parcel.v3'
            x-stoplight:
              id: fg0pldgeqxskl
        shipper_account:
          $ref: '#/components/schemas/Reference.v3'
          x-stoplight:
            id: ca9pepi3lt94n
        created_at:
          type: string
          x-stoplight:
            id: gsq5ui26timom
          description: A formatted date
        updated_at:
          type: string
          x-stoplight:
            id: t4i229d75aonh
          description: A formatted date
    Pickup_parcel.v3:
      x-stoplight:
        id: rg6vxf4hy1fwr
      title: PickupParcel
      type: object
      description: 'PickupParcel object: the description of pickup parcel information'
      x-tags:
      - Primitive
      required:
      - weight
      - quantity
      properties:
        weight:
          $ref: '#/components/schemas/Weight.v3'
          x-stoplight:
            id: n58yvlrsix94t
        quantity:
          type: integer
          x-stoplight:
            id: cvh46u2j0b88f
          description: 'The quantity of the packages. Minimum: 1'
        service_type:
          type: string
          x-stoplight:
            id: 44aaqvxjye7j3
          description: Service Type. Required for `UPS` and `DHL Express`
        dimension:
          $ref: '#/components/schemas/Dimension.v3'
          x-stoplight:
            id: vf9xym5596paa
    Address.v3:
      type: object
      x-stoplight:
        id: c01e28f80783b
      x-examples:
        example-1:
          country: HKG
          contact_name: Sir Foo
          phone: '11111111'
          fax: +1 206-654-3100
          email: foo@foo.com
          company_name: Foo Store
          street1: Workshop A, 10/F, Wah Shing Industrial Building
          street2: 18 Cheung Shun Street, Lai Chi Kok
          city: Lai Chi Kok
          type: business
          postal_code: null
          state: null
          street3: null
          tax_id: null
      title: Address
      description: 'Address object: the description of address information'
      x-tags:
      - Primitive
      examples: []
      required:
      - street1
      - country
      - contact_name
      properties:
        street1:
          type: string
          description: 'address_line1 of address

            '
        country:
          type: string
          description: Country in ISO 3166-1 alpha 3 code
        contact_name:
          type: string
          description: contact_name of address
        phone:
          type: string
          description: contact_phone of address
        fax:
          type:
          - string
          - 'null'
          description: fax_number of address
        email:
          type:
          - string
          - 'null'
          description: email of address
        company_name:
          type:
          - string
          - 'null'
          description: company_name of address
        street2:
          type:
          - string
          - 'null'
          description: address_line2 of address
        street3:
          type:
          - string
          - 'null'
          description: address_line3 of address
        city:
          type:
          - string
          - 'null'
          description: city of address
        state:
          type:
          - string
          - 'null'
          description: state of address
        postal_code:
          type:
          - string
          - 'null'
          description: postal_code of address
        type:
          type:
          - string
          - 'null'
          description: type of address
          enum:
          - residential
          - business
        tax_id:
          type:
          - string
          - 'null'
          description: tax id
        tax_id_type:
          type:
          - string
          - 'null'
          description: 'tax id type. Only applies to DHL Express, DHL eCommerce US, DHL eCommerce UK.

            - vat: Value-Added tax

            - gst: Goods and Service Tax

            - eori: European Union Registration and Identification

            - ioss: Import One Stop Shop

            - pan: Pan-Aarav

            - ukims: UK Internal Market Scheme

            - other: Other

            '
          x-stoplight:
            id: 7rtl96ei81zeb
          enum:
          - vat
          - gst
          - eori
          - ioss
          - pan
          - ukims
          - other
        identification_number:
          type:
          - string
          - 'null'
          description: identification number
          x-stoplight:
            id: u1nqwj1dvhw67
        identification_type:
          type:
          - string
          - 'null'
          description: 'identification type

            - mil: Military Number

            - nid: National Identity Card

            - pas: Passport

            - other: Other'
          x-stoplight:
            id: gh9ttmhi0xmik
          enum:
          - mil
          - nid
          - pas
          - other
        eori_number:
          type:
          - string
          - 'null'
          description: eori number
        location:
          type:
          - object
          - 'null'
          properties:
            lat:
              type: number
              description: latitude number
            lng:
              type: number
              description: longitude number
    Dimension.v3:
      title: Dimension
      x-stoplight:
        id: k8cgrqqlq38rn
      type: object
      description: 'Dimension object: the description of width/height/depth information'
      x-tags:
      - Primitive
      examples: []
      properties:
        width:
          type: number
          description: width
        height:
          type: number
          description: height
        depth:
          type: number
          description: depth
        unit:
          type: string
          description: unit
          enum:
          - cm
          - in
          - mm
          - m
          - ft
          - yd
      required:
      - width
      - height
      - depth
      - unit
    Error.v3:
      type: object
      title: Error
      description: Each error object contains a "path" key and an "info" key. The "path" is the JSON path of the request object to indicate the error location. The "info" is a human-readable description of the error.
      examples:
      - path: data.shipment.ship_from.country
        info: data.shipment.ship_from.country is a required property
      additionalProperties: false
      x-tags:
      - Envelope
      properties:
        path:
          type: string
          description: The json path of the request object to indicate the error location
          example: account.email
        info:
          type: string
          description: A human-readable description of the error.
          example: account.email is invalid
  securitySchemes:
    as-api-key:
      name: as-api-key
      type: apiKey
      in: header