Skip to main content

Retrieve a purchase intent

You can retrieve the purchase intents made for your organization and examine their progress.

To retrieve all the purchase intents, issue a GET request to the purchase-intents endpoint.

GET https://public-api.phosphor.xyz/v1​/purchase-intents

This endpoint supports query by a number of parameters including:

  • item_id: The item ID that the purchase intent is made against.
  • collection_id: The collection ID that the purchase intent is made against.
  • listing_id: The listing ID that the purchase intent is made against.
  • status: The purchase intent status. Accepted values are PENDING, UNRESOLVED, CANCELLED, CONFIRMED and EXPIRED.
  • email: The buyer's email address.
  • eth_address: The buyer's ethereum address.
  • fulfillment_status: The fulfillment status of the purchase intent. Accepted values are PENDING, ASSIGNED, COMPLETED, EXCEPTION. You can specify one or more values with a list.
  • fulfillment_method: The fulfillment method of the purchase intent. Accepted values are EMAIL, TRANSFER, VOUCHER. You can specify one or more values with a list.
  • payment_provider: The payment provider of the purchase intent. Accepted values are STRIPE, MINT_VOUCHER, and EMAIL_CLAIM. You can specify one or more values with a list.
GET https://public-api.phosphor.xyz/v1/purchase-intents?status=PENDING&payment_provider=STRIPE, MINT_VOUCHER

It is a paginated endpoint that returns results up to a certain limit.

  • Specify the cursor from the previous response to return the next batch of results from the offset.
  • Specify an order_direction of ASC or DESC to sort results in an ascending or descending order.
GET https://public-api.phosphor.xyz/v1/purchase-intents?limit=1&order_direction=DESC
Example response
{
  "cursor": "c3QAMQ..",
  "has_more": true,
  "results": [
    {
      "created_at": "2023-01-26T14:02:10.352195+00:00",
      "email": "aaa@bbb.com",
      "eth_address": "0xa99D7eD4bB4E3EEFed18a0269bE46Aa8c49Ab165",
      "expiration": "2023-01-26T14:04:10.321710",
      "fulfillment_method": "EMAIL",
      "fulfillment_status": "PENDING",
      "id": "6430cc30-016e-4ae1-b35b-a7e80a5112fb",
      "item_claim_ids": null,
      "listing_id": "aa2536ac-efc0-4c1b-8ee7-9abad7e8e964",
      "payment_provider": "STRIPE",
      "provider_price": {
        "currency": "USD",
        "price": 25000
      },
      "status": "CANCELLED",
      "stripe_payment_intent_id": "pi_client_secret",
      "transaction_ids": null
    }
  ],
  "total_results": 21
}
  • cursor indicates an offset from which the next batch of results begin.
  • has_more returns true if there are more results than already displayed.
  • results returns an array of listings from the search.
  • total_results returns the total number of results from the response.

To retrieve a specific purchase intent by the purchase intent id,

GET https://public-api.phosphor.xyz/v1​/purchase-intents/{purchase_intent_id}
Example response
{
  "created_at": "2023-01-26T14:02:10.352195+00:00",
  "email": "aaa@bbb.com",
  "eth_address": "0xa99D7eD4bB4E3EEFed18a0269bE46Aa8c49Ab165",
  "expiration": "2023-01-26T14:04:10.321710",
  "fulfillment_method": "EMAIL",
  "fulfillment_status": "PENDING",
  "id": "6430cc30-016e-4ae1-b35b-a7e80a5112fb",
  "item_claim_ids": null,
  "listing_id": "aa2536ac-efc0-4c1b-8ee7-9abad7e8e964",
  "payment_provider": "STRIPE",
  "provider_price": {
    "currency": "USD",
    "price": 25000
  },
  "status": "CANCELLED",
  "stripe_payment_intent_id": "pi_client_secret",
  "transaction_ids": null
}
  • created_at: Time that the purchase intent was received.
  • email: The buyer's email address.
  • eth_address: The buyer's ethereum address.
  • expiration: Time that the purchase intent expires if no payment is confirmed.
  • fulfillment_method: EMAIL or TRANSFER. If the buyer provides an email address, the fulfillment method will be EMAIL. If the buyer provides an ethereum address, the fulfillment method will be TRANSFER. If a buyer provides both, the platform defaults to EMAIL.
  • fulfillment_status: Status of the fulfillment stage after payment is received.
    • PENDING: Purchase intent has not been fulfilled yet. The payment has been made and the item is awaiting delivery.
    • ASSIGNED: Items have been assigned to the purchase intent.
    • COMPLETED: Successfully fulfilled. The item has been successfully delivered.
    • EXCEPTION: Failed fulfillment. An unrecoverable error has occurred while attempting to deliver and manual intervention is needed.
  • id: An internal ID by the platform for this purchase intent.
  • item_claim_ids: IDs of the email claims if the fulfillment method is EMAIL.
  • listing_id: The listing ID that the purchase intent is made against.
  • payment_provider: The payment provider of the purchase intent.
  • provider_price: The price in the settlement currency, if the listing currency is different from the settlement currency accepted by the payment provider. See listing currencies for information on how the platform converts price.
  • status: The status of the purchase intent.
    • PENDING: The purchase intent is awaiting payment.
    • UNRESOLVED: There has been an issue with the payment. This could be that a purchase intent is underpaid, or overpaid, or that the card is declined. Check your payment provider's dashboard for more details.
    • CANCELLED: The purchase intent has been cancelled.
    • CONFIRMED: The purchase intent has received payment. The fulfillment stage will begin.
    • EXPIRED: The purchase intent has expired.
  • stripe_payment_intent_id: A unique identifier of the Stripe PaymentIntent. The platform communicates with Stripe through this unique identifier.
  • transaction_ids: IDs of the pending transactions if the fulfillment method is TRANSFER.
Last updated on