# Get Stamps Transaction Report

This Operation returns the report of stamps transactions within the specified date range.

Endpoint: GET /api/v1/stamps
Version: 1.0.0
Security: bearerAuth

## Query parameters:

  - `startDate` (string)
    Start date for the transaction report, in UTC format (e.g., `2025-08-01T00:00:00Z`). default start date is today.

  - `endDate` (string)
    End date for the transaction report, in UTC format (e.g., `2025-08-15T23:59:59Z`). Default end date is today.

  - `size` (number)
    Number of transaction reports per page. Used for pagination.

  - `page` (number)
    Page number to fetch in paginated results.

  - `refundEligible` (boolean)
    Filter shipments eligible for refund.

## Response 200 fields (application/json):

  - `stamps` (object)
    Details about the generated stamp and shipment.

  - `stamps.stampId` (string)
    Unique identifier of the stamp.
    Example: USPS2201368505487673

  - `stamps.fromAddress` (object)
    Sender's address details.

  - `stamps.fromAddress.addressLines` (array)
    Street address lines of the sender.
    Example: ["24182 Kathy Ave"]

  - `stamps.fromAddress.cityTown` (string)
    City or town of the sender.
    Example: Lake Forest

  - `stamps.fromAddress.stateProvince` (string)
    State or province of the sender.
    Example: CA

  - `stamps.fromAddress.postalCode` (string)
    Postal or ZIP code.
    Example: 92630-1827

  - `stamps.fromAddress.countryCode` (string)
    Country code in ISO 2-letter format.
    Example: US

  - `stamps.fromAddress.name` (string)
    Sender’s name.
    Example: Steve Smith

  - `stamps.fromAddress.phone` (string)
    Sender’s phone number.
    Example: 1112223334

  - `stamps.fromAddress.residential` (boolean)
    Indicates if the address is residential.
    Example: false

  - `stamps.fromAddress.lastVerifiedDate` (string)
    Date when the address was last verified.
    Example: 0001-01-01T00:00:00Z

  - `stamps.parcelWeight` (object)
    Weight details of the parcel.

  - `stamps.parcelWeight.unitOfMeasurement` (string)
    Weight unit of measurement.
    Example: OZ

  - `stamps.parcelWeight.weight` (number)
    Weight of the parcel.
    Example: 2

  - `stamps.parcelDimension` (object)
    Dimensions of the parcel, if provided.

  - `stamps.rate` (object)
    Rate and service details.

  - `stamps.rate.carrier` (string)
    Carrier handling the shipment.
    Example: USPS

  - `stamps.rate.parcelType` (string)
    Type of parcel (e.g., LTR, PKG).
    Example: LTR

  - `stamps.rate.parcelName` (string)
    Human-readable name for the parcel type.
    Example: Letter

  - `stamps.rate.serviceId` (string)
    The unique identifier given to the carrier specific service.
    Example: FCM

  - `stamps.rate.serviceName` (string)
    Name of the shipping service.
    Example: First-Class Mail®

  - `stamps.rate.specialServices` (array)
    List of special services applied.

  - `stamps.rate.specialServices.specialServiceId` (string)
    Unique identifier of the special service.
    Example: ERR

  - `stamps.rate.specialServices.brandedName` (string)
    Branded name of the service.
    Example: ERR

  - `stamps.rate.specialServices.fee` (number)
    Service fee.
    Example: 2.82

  - `stamps.rate.specialServices.appliedFactor` (object)
    Applied factor for fee calculation.

  - `stamps.rate.specialServices.appliedFactor.value` (object)

  - `stamps.rate.baseCharge` (number)
    Base shipping charge.
    Example: 1.03

  - `stamps.rate.totalCarrierCharge` (number)
    Total carrier charge including base and services.
    Example: 11.15

  - `stamps.rate.rateTypeId` (string)
    Rate type applied to the shipment.
    Example: METERED_RATE

  - `stamps.toAddress` (object)
    The complete address of the Recipient.

  - `stamps.toAddress.name` (string)
    The name of the Recipient.
    Example: Recipient Name

  - `stamps.toAddress.addressLine1` (string)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Recipient.  `Max length = 35`.
    Example: 350 Fifth Avenue

  - `stamps.toAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `stamps.toAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `stamps.toAddress.cityTown` (string)
    The name of the city or town the Recipient belongs to.  `Max length = 30`.
    Example: New York

  - `stamps.toAddress.stateProvince` (string)
    "The name of the State or Province the Sender belongs to. It is the `2-letter` State or Province Code for US or Canadian address(es).
 Below is the hyperlink for CA country that will navigate to its Province/State Codes page. Similarly, respective country users can check for their country- State/Province codes.
 Please switch to the `Search` tab, select `Country codes` radio button, enter the required country name or country code, and then click `SEARCH` button .  `Max length = 2`"
    Example: NY

  - `stamps.toAddress.postalCode` (string)
    "The Postal Code or ZIP Code of the address. For CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'. While for US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'."
    Example: 10118

  - `stamps.toAddress.countryCode` (string)
    "The country in which the recipient's address is located. The value will be the two-character ISO Code of the country from the ISO country list.  Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.
 Below is the hyperlink, please select `Country codes` and then click `SEARCH` button. "
    Example: US

  - `stamps.toAddress.company` (string)
    The name of the company, in case if the recipient address is not residential.
    Example: PB

  - `stamps.toAddress.phone` (string)
    This is Recipient's phone number. Enter the digits with or without spaces or hyphens.
    Example: 332 555-1212

  - `stamps.toAddress.email` (string)
    This must be recipient's valid email. Email is required if the customer is using GoFor Carrier.
    Example: recipient@gmail.com

  - `stamps.toAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `stamps.toAddress.isPOBox` (boolean)
    Checks if the specified address has the PO Box. In case if Yes, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `stamps.toAddress.lastVerifiedDate` (string)
    Date when the address was last verified.
    Example: 0001-01-01T00:00:00Z

  - `stamps.trackingNumber` (string)
    Tracking number for the shipment.
    Example: 9414809898643519098588

  - `stamps.spoiled` (boolean)
    Indicates if the stamp was spoiled.
    Example: false

  - `stamps.stampOptions` (array)
    Additional options for configuring stamp-related settings.

  - `stamps.stampOptions.name` (string)
    The name of the stamp option.
    Example: SHIPPER_ID

  - `stamps.stampOptions.value` (string)
    The corresponding value for the stamp option.
    Example: 9015256782

  - `subscriptionId` (string)
    Identifier of the subscription associated with the transaction.
    Example: sa87bf0

  - `locationId` (string)
    Location identifier where the transaction was created.
    Example: mxpAx49Nd2a

  - `userEmail` (string)
    User email associated with the transaction.
    Example: API-SP360-BweE7YNeKoa-DEV

  - `memo` (string)
    Memo for the transaction.
    Example: mentoTestRef

  - `type` (string)
    Transaction type (e.g., ERRBarcode).
    Example: ERRBarcode

  - `envelopeSize` (string)
    Size of the envelope used for the stamp.
    Example: 10

  - `transactionId` (string)
    Unique identifier of the transaction.
    Example: O8K3AEkJDwRwdq39YkqGv

  - `correlationId` (string)
    Key assigned by the shipping system to the transaction.
    Example: 60700bcd990b41b2a278b3708f536183

  - `transactionCreateDate` (string)
    Date and time when the transaction was created.
    Example: 2025-08-12T07:24:52.665Z

  - `status` (string)
    Current status of the transaction.
    Example: COMPLETE

  - `imageUrl` (string)
    URL to the stamp image.
    Example: https://prv-labels-cls.gcs.pitneycloud.com/usps/456312111/outbound/stamp/60700bcd990b41b2a278b3708f536183.gif

  - `stampsList` (array)
    List of stamps created in this transaction.

  - `printStatus` (object)
    Details about print and ledger status.

  - `printStatus.ledgerStatus` (string)
    Status of ledger entry.
    Example: SUCCESS

  - `printStatus.printStatus` (boolean)
    Indicates if the stamp was successfully printed.
    Example: true

  - `printStatus.deviceHub` (boolean)
    Indicates if DeviceHub was used.
    Example: false

  - `printStatus.eligibleForRecovery` (boolean)
    Indicates if the transaction is eligible for recovery.
    Example: false

  - `subCarrierID` (string)
    Identifier for the sub-carrier (if applicable).
    Example: eRMnRx4mzPP

  - `dispenseClient` (string)
    Client type used for dispensing (e.g., API, UI).
    Example: api

  - `locationName` (string)
    Name of the location where the transaction was created.
    Example: Default Location

  - `consType` (integer)
    Consumer type code associated with the transaction.
    Example: 0

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g. validation-error.
    Example: validation_error

  - `errorDescription` (string)
    The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
    Example: Rategrop cannot created.

  - `additionalCode` (string)
    A unique identifier for the error, for example 01000806.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing.

  - `additionalParameters` (array)

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.