Models Reference

Every request and response shape has a typed Pydantic model. This page is a quick index of what each model represents and the fields you’ll use most often. For the full, auto-generated field lists, see the API Reference.

You can import any of these from the top-level package:

from pypresscart import Order, Campaign, CheckoutRequest, TokenInfo  # etc.

Models accept unknown fields silently — so if Presscart adds a new field, your existing code won’t break. See Forward compatibility at the bottom.

Shared primitives

Paginated[T]

Generic pagination envelope. Documented in Pagination.

class Paginated[T]:
    records: list[T]
    total_records: int | None
    total_pages: int | None
    current_page: int | None
    next_page: int | None
    previous_page: int | None

Tag

class Tag:
    name: str

Price

class Price:
    unit_amount: float      # see note below
    currency: str | None    # usually "usd"
    pricing_tier: str | None

Warning

Monetary units are not uniform across the Presscart API. On /products/listings, /products/{id}, and outlet channel prices, unit_amount is returned in cents (integer, e.g. 575 means $5.75). On /orders*, the money fields (total, subtotal, processing_fee, discount, etc.) come back in dollars (float, e.g. 154.5 means $154.50). pypresscart surfaces whatever the API returns — always confirm the unit for the endpoint you’re on before formatting.

IncludeItem

class IncludeItem:
    channel_type: ChannelType | str | None
    placement_type: PlacementType | str | None

Both types are nullable because the API occasionally returns null for them.

Enums

class ChannelType(str, Enum):
    WEBSITE, NEWSLETTER, INSTAGRAM, LINKEDIN,
    YOUTUBE, TIKTOK, TWITTER_X, PODCAST, OTHER

class PlacementType(str, Enum):
    FULL_FEATURE, PRESS_RELEASE, MENTION, QUOTE, LISTICLE

class OutletStatus(str, Enum):
    ACTIVE, INACTIVE, DRAFT, PENDING_REVIEW,
    PENDING_AGREEMENT, REJECTED, ARCHIVED, SUSPENDED

class TokenType(str, Enum):
    FULL_ACCESS = "full_access"
    CUSTOM = "custom"
    READ_ONLY = "read_only"

class SortOrder(str, Enum):
    ASC = "asc"
    DESC = "desc"

All enums accept either the enum value or a raw string — models declare the type as Enum | str for forward compatibility.

Auth

TokenInfo

Response from Auth.whoami().

Field	Type
source	str
team_id	str
token_type	TokenType | str
scopes	list[str]
pro_pricing_enabled	bool | None

Outlets

Outlet

Full outlet with outlet_channels, tags, metadata. Returned by client.outlets.get().

OutletListing

A row in client.outlets.list() / client.outlets.list_products(). id is a product id; outlet_id is the outlet.

OutletChannel, OutletChannelSummary

The detailed and summary forms of a channel on an outlet.

CountriesResponse, StatesResponse, CitiesResponse

Wrappers around {"countries": [...]} / {"states": [...]} / {"cities": [...]}.

DisclaimerRecord

class DisclaimerRecord:
    id: str
    name: str | None
    description: str | None

Products

Product

Full product (from client.products.get()).

ProductListing

Row in client.products.list_listings().

ProductCategoryCount

class ProductCategoryCount:
    type: str    # e.g. "FULL_FEATURE"
    count: int

Orders

Order

Full order; includes nested line_items, team, and payment metadata. See Orders.

LineItem

A single line on an order.

CheckoutRequest

Body for client.orders.create_checkout().

Field	Type
profile_id	str
line_items	list[CheckoutLineItem]
discount	float | None (default 0)

CheckoutLineItem

Field	Type
product_id	str
quantity	int (default 1)
is_add_on	bool (default False)
linked_order_line_item_id	str | None

OutletRef, TeamRef

Minimal embedded references inside Order.

Order Items

OrderItem

Team-wide order item (GET /order-items). Fields cover commissions, accounting, refunds, publisher payouts, and nested article/outlet/client references.

ProfileOrderItem

Slimmer shape returned by client.profiles.list_order_items() (bare-array endpoint).

Profiles

Profile

Brand/entity the team promotes.

Field	Type	Notes
id, name	str
type	str	e.g. "COMPANY", "INDIVIDUAL"
primary_goals	list[str]	e.g. ["BRAND_AWARENESS"]
website_url, logo, location	str | None
(many more)		see source

Campaigns

Campaign

Full campaign, including optional nested profile, questionnaire, articles.

CampaignCreateRequest

See Campaigns — all fields required at the schema level, though many may be None.

CampaignUpdateRequest

All fields optional.

Questionnaire

Linked brief/research attached to a campaign.

AssignOrderItemsRequest

class AssignOrderItemsRequest:
    order_item_ids: list[str]

QuestionnaireLinkRequest

Field	Type
file_id	str
file_url	str
file_name	str
file_size	int

ArticleStatus, ArticleStatusCount

Status change entries / aggregate counts.

Articles

Article

Full article (from client.articles.get()).

CampaignArticleRow

Row in client.campaigns.list_articles().

ArticleUpdateRequest

Field	Type
name	str | None
brief_google_doc_url	str | None

ApproveDraftRequest

class ApproveDraftRequest:
    draft_google_doc_url: str | None

ArticleWriter, ArticleOrderItem, ArticleStatusRef

Embedded references.

Files

File

A file record with file_key, file_url, size, mime_type, folder_id, timestamps.

UploadedFile, UploadFilesResponse

Shape returned by client.files.upload():

class UploadFilesResponse:
    files: list[UploadedFile]

MoveFilesRequest

class MoveFilesRequest:
    file_ids: list[str]
    folder_id: str | None

MoveFilesResponse

class MoveFilesResponse:
    moved_count: int

DeleteFileResponse

class DeleteFileResponse:
    success: bool

Folders

Folder

class Folder:
    id: str
    name: str | None
    team_id: str | None
    created_by: str | None
    created_at: datetime | None
    updated_at: datetime | None
    deleted_at: datetime | None

FolderCreateRequest, FolderRenameRequest

class FolderCreateRequest:
    name: str

class FolderRenameRequest:
    name: str

DeleteFolderResponse

class DeleteFolderResponse:
    success: bool

Working with models

Construct

from pypresscart import CheckoutRequest, CheckoutLineItem

body = CheckoutRequest(
    profile_id="prof_1",
    line_items=[CheckoutLineItem(product_id="prod_1")],
)

Validate from a dict

from pypresscart import Order

order = Order.model_validate(raw_dict)

Dump to JSON-compatible dict

body.model_dump(mode="json", exclude_none=True)

Forward compatibility

If Presscart adds a new field to a response, pypresscart won’t raise a validation error — the extra data is preserved on the parsed model (accessible as model.model_extra) but not typed. Upgrade the library to pick up the typed attribute once it’s available.

Lenient parsing

The API occasionally sends an empty string ("") in place of null for optional fields — especially booleans and dates. pypresscart normalizes "" to None before validation, so you don’t get spurious type errors on what is semantically a missing value.

If you need the raw payload byte-for-byte, use as_json=True (see Dual-Mode I/O).